AdeliAPI
Dashboard
Documentation menu

Analytics

Platform-specific endpoints. Unlike accounts, posts, and messages, these are deliberately not normalized into a shared shape — the providers measure genuinely different things, and flattening them would invent numbers none of them reports.

All of them are single-account reads, so none uses the aggregate envelope.

GET/api/v1/analytics/instagram/account-insightsInstagram account insights

Returns Instagram's own insight records for a rolling 28-day window, covering views, reach, total_interactions, and accounts_engaged.

Query parameters

accountIduuidRequired
A connected Instagram account.
profileIduuid
Defaults to your key's profile.
curl --fail-with-body \
"$ADELI_URL/api/v1/analytics/instagram/account-insights?accountId=$ACCOUNT_ID" \
-H "Authorization: Bearer $ADELI_API_KEY"
json
{
  "platform": "instagram",
  "accountId": "00000000-0000-0000-0000-000000000000",
  "profileId": "00000000-0000-4000-8000-000000000001",
  "insights": [{ "name": "reach", "values": [] }],
  "fetchedAt": "2026-04-01T12:00:00.000Z"
}

An empty insights array is normal

Instagram omits metrics entirely for accounts with too few followers or too little history, and its data lags by up to 48 hours. Render a missing metric as unavailable rather than as zero — they mean different things.

insights is Instagram's array, passed through unchanged. Adeli does not store history, so each call is a live read.

Errors — 401 unauthorized, 400 invalid_request, 404 account_not_found, 404 profile_not_found, 422 connection_expired, 422 provider_not_configured, 502 provider_error.

GET/api/v1/analytics/tiktok/account-analyticsTikTok account analytics

Returns the TikTok account's profile and lifetime counters, read from TikTok API for Business. For daily figures and audience demographics use TikTok account insights below.

Query parameters

accountIduuidRequired
A connected TikTok account.
profileIduuid
Defaults to your key's profile.
json
{
  "platform": "tiktok",
  "accountId": "00000000-0000-0000-0000-000000000000",
  "profileId": "00000000-0000-4000-8000-000000000001",
  "profile": {
    "openId": "app-scoped-open-id",
    "username": "creator",
    "displayName": "Creator",
    "avatarUrl": "https://example.com/avatar.jpg",
    "profileDeepLink": "https://www.tiktok.com/@creator",
    "bioDescription": "Profile bio",
    "isVerified": false,
    "isBusinessAccount": true
  },
  "analytics": { "followers": 1200, "following": 80, "likes": 5400, "videos": 42 },
  "fetchedAt": "2026-04-01T12:00:00.000Z"
}

openId is TikTok's app-scoped id for the account. isBusinessAccount tells a TikTok Business Account from a personal one; some insight fields below exist only for business accounts.

Errors — 401 unauthorized, 400 invalid_request, 404 account_not_found, 404 profile_not_found, 422 connection_expired, 422 provider_not_configured, 429 rate_limited, 502 provider_error.

GET/api/v1/analytics/tiktok/account-insightsTikTok account insights

Returns the account's daily metrics and follower demographics for a window of complete UTC days. Needs the user.insights permission, which every connection made since Adeli moved to TikTok API for Business has granted.

Query parameters

accountIduuidRequired
A connected TikTok account.
profileIduuid
Defaults to your key's profile.
startDateYYYY-MM-DD
First day, UTC. At most 60 days ago. Give both dates or neither; the default is the last 28 complete days.
endDateYYYY-MM-DD
Last day, UTC, before today and on or after startDate.
curl --fail-with-body "$ADELI_URL/api/v1/analytics/tiktok/account-insights?accountId=$ACCOUNT_ID&startDate=2026-09-01&endDate=2026-09-28" -H "Authorization: Bearer $ADELI_API_KEY"
json
{
  "platform": "tiktok",
  "accountId": "00000000-0000-0000-0000-000000000000",
  "profileId": "00000000-0000-4000-8000-000000000001",
  "isBusinessAccount": true,
  "startDate": "2026-09-01",
  "endDate": "2026-09-28",
  "daily": [
    {
      "date": "2026-09-01",
      "videoViews": 1126, "uniqueVideoViews": 900, "profileViews": 40,
      "likes": 26, "comments": 4, "shares": 1,
      "followers": 1204, "newFollowers": 6, "lostFollowers": 2, "engagedAudience": 120,
      "bioLinkClicks": 3, "emailClicks": 0, "phoneNumberClicks": 0, "addressClicks": 0,
      "appDownloadClicks": 0, "leadSubmissions": 0,
      "activity": [{ "hour": "18", "count": 52 }]
    }
  ],
  "audience": {
    "ages": [{ "key": "18-24", "percentage": 0.42 }],
    "genders": [{ "key": "Female", "percentage": 0.6 }],
    "countries": [{ "key": "US", "percentage": 0.75 }],
    "cities": [{ "key": "Austin", "percentage": 0.08 }]
  },
  "fetchedAt": "2026-09-29T12:00:00.000Z"
}

null means TikTok did not report it

TikTok's daily figures lag by 24 to 48 hours and exist only while Analytics is turned on in the TikTok app. Unique views, follower gains and losses, engaged audience, and activity are reported for Business Accounts only; the click metrics need a verified or registered business; demographics and activity need at least 100 followers. Anything TikTok withholds is null or an empty list, never 0.

activity is when followers were active, by hour. percentage values are fractions of 1.

Errors — 401 unauthorized, 400 invalid_request, 404 account_not_found, 404 profile_not_found, 422 connection_expired (also returned when the connection lacks user.insights; reconnecting fixes it), 422 provider_not_configured, 429 rate_limited, 502 provider_error.

GET/api/v1/analytics/tiktok/video-insightsTikTok post insights

Returns counters and watch metrics for specific TikTok posts, or for the most recent page of posts when videoIds is omitted. Needs the video.insights permission.

Query parameters

accountIduuidRequired
A connected TikTok account.
profileIduuid
Defaults to your key's profile.
videoIdsstring
Comma-separated TikTok post ids (providerId from GET /api/v1/posts, or postIds from a publish status), at most 20.
json
{
  "platform": "tiktok",
  "accountId": "00000000-0000-0000-0000-000000000000",
  "profileId": "00000000-0000-4000-8000-000000000001",
  "videos": [
    {
      "id": "6990565363377392901",
      "mediaType": "VIDEO",
      "isAd": false,
      "caption": "little coco",
      "coverImageUrl": "https://p16-sign-va.tiktokcdn.com/...",
      "shareUrl": "https://www.tiktok.com/@creator/video/6990565363377392901",
      "embedUrl": "https://www.tiktok.com/player/v1/6990565363377392901",
      "durationSeconds": 20,
      "likeCount": 10, "commentCount": 2, "shareCount": 0, "favoriteCount": 1,
      "viewCount": 1231, "reach": 154,
      "createdAt": "2021-07-30T04:03:55.000Z",
      "insights": {
        "totalTimeWatchedSeconds": 695.9,
        "averageTimeWatchedSeconds": 4.1,
        "fullVideoWatchedRate": 0.0237,
        "newFollowers": 2,
        "profileViews": 9,
        "retention": [{ "second": "1", "percentage": 0.82 }],
        "impressionSources": [{ "key": "For You", "percentage": 0.8983 }],
        "audienceGenders": [], "audienceCountries": [{ "key": "US", "percentage": 0.7574 }],
        "audienceCities": [], "audienceTypes": []
      }
    }
  ],
  "fetchedAt": "2026-09-29T12:00:00.000Z"
}

A post that has barely been watched may have no reach or watch metrics yet; those come back null or empty. coverImageUrl is a signed TikTok URL that expires, so fetch it again rather than storing it. TikTok stops updating a post's figures 365 days after it is published.

Errors — 401 unauthorized, 400 invalid_request, 404 account_not_found, 404 profile_not_found, 422 connection_expired (also returned when the connection lacks video.insights), 422 provider_not_configured, 429 rate_limited, 502 provider_error.

GET/api/v1/analytics/facebook/page-metricsFacebook Page metrics

Returns the Page's own details and audience size, engagement totalled across its recent posts, and Page Insights for the last 28 days.

Query parameters

accountIduuid
A connected Facebook Page. Defaults to the profile's Page.
profileIduuid
Defaults to your key's profile.
json
{
  "platform": "facebook",
  "accountId": "00000000-0000-0000-0000-000000000000",
  "profileId": "00000000-0000-0000-0000-000000000000",
  "page": { "id": "1234567890", "name": "Jasper\u2019s Market", "username": "jaspers", "category": "Grocery Store", "link": "https://www.facebook.com/jaspers" },
  "metrics": { "followers": 980, "fans": 960, "recentPosts": 10, "recentPostLikes": 42, "recentPostComments": 7, "recentPostShares": 3 },
  "insights": {
    "periodDays": 28,
    "views": 4200,
    "engagements": 310,
    "pageViews": 75,
    "followers": 990,
    "daily": [{ "date": "2026-09-20T07:00:00+0000", "value": 150 }]
  },
  "insightsUnavailable": null,
  "fetchedAt": "2026-09-21T12:00:00.000Z"
}

insights

viewsnumber | null
Times the Page's content was on screen over the window (Meta's page_media_view), summed.
engagementsnumber | null
Reactions, comments, shares, and clicks on the Page's posts (page_post_engagements), summed.
pageViewsnumber | null
Visits to the Page itself (page_views_total), summed.
followersnumber | null
Followers on the latest day Meta reported (page_follows).
dailyarray
Daily views, oldest first, as { date, value }.

When insights is null

Page Insights need the read_insights permission. A Facebook connection made before Adeli requested it, or one where it was declined, returns "insights": null with "insightsUnavailable": "permission_missing"; reconnecting Facebook fixes it. "analyze_task_missing" means Meta refused even with the permission, because the person who connected the Page cannot view its insights. "provider_error" means Meta failed the request. The rest of the response is returned either way. A figure Meta did not report is null, not 0; small or new Pages often have none yet.

Errors — 401 unauthorized, 400 invalid_request, 404 account_not_found, 409 page_not_selected, 422 connection_expired, 422 provider_not_configured, 502 provider_error.

GET/api/v1/analytics/youtube/channel-insightsYouTube channel insights

Returns the channel's stored details and, from YouTube Analytics, its daily metrics, top ten videos, and viewer demographics over a window. YouTube's figures lag by two to three days, so the default window is the 28 days ending three days ago. Needs the yt-analytics.readonly grant; a connection without it returns 422 connection_expired with "Reconnect YouTube to enable analytics".

Query parameters

accountIduuidRequired
A connected YouTube channel.
profileIduuid
Defaults to your key's profile.
startDateYYYY-MM-DD
First day, UTC. Give both dates or neither. A window covers at most 365 days.
endDateYYYY-MM-DD
Last day, UTC, before today and on or after startDate.
json
{
  "platform": "youtube",
  "accountId": "00000000-0000-0000-0000-000000000000",
  "profileId": "00000000-0000-4000-8000-000000000001",
  "channel": { "channelId": "UCxxxxxxxxxxxxxxxxxxxxxx", "title": "Bird Channel", "handle": "@birds", "avatarUrl": "https://yt3.ggpht.com/...", "subscribers": 1500, "views": 90000, "videos": 12 },
  "insights": {
    "startDate": "2026-09-05",
    "endDate": "2026-10-02",
    "daily": [
      { "date": "2026-10-02", "views": 600, "minutesWatched": 1100, "averageViewDurationSeconds": 70, "subscribersGained": 5, "subscribersLost": 1, "likes": 20, "comments": 2, "shares": 0 }
    ],
    "topVideos": [{ "videoId": "dQw4w9WgXcQ", "views": 400, "minutesWatched": 800, "averageViewDurationSeconds": 65, "likes": 15, "comments": 2 }],
    "audience": {
      "ageGender": [{ "ageGroup": "age25-34", "gender": "female", "percentage": 31.5 }],
      "countries": [{ "country": "US", "views": 750 }]
    }
  },
  "fetchedAt": "2026-10-05T12:00:00.000Z"
}

channel.subscribers is null when the channel hides its subscriber count. YouTube withholds demographics for channels with too few viewers, so audience can be empty.

Errors — 401 unauthorized, 400 invalid_request, 404 account_not_found, 404 profile_not_found, 422 connection_expired, 422 provider_not_configured, 429 rate_limited, 502 provider_error.

GET/api/v1/analytics/youtube/video-insightsYouTube video insights

Returns watch metrics for specific videos, or for the channel's 20 newest, over the same kind of window. Needs yt-analytics.readonly, like channel insights.

Query parameters

accountIduuidRequired
A connected YouTube channel.
profileIduuid
Defaults to your key's profile.
videoIdsstring
Comma-separated YouTube video ids (providerId from GET /api/v1/posts), at most 50. Omit for the 20 newest.
startDateYYYY-MM-DD
Give both dates or neither; the default is the 28 days ending three days ago.
endDateYYYY-MM-DD
json
{
  "platform": "youtube",
  "accountId": "00000000-0000-0000-0000-000000000000",
  "profileId": "00000000-0000-4000-8000-000000000001",
  "insights": {
    "startDate": "2026-09-05",
    "endDate": "2026-10-02",
    "videos": [
      { "videoId": "dQw4w9WgXcQ", "views": 400, "minutesWatched": 800, "averageViewDurationSeconds": 65, "averageViewPercentage": 54.2, "likes": 15, "comments": 2, "shares": 1, "subscribersGained": 3 }
    ]
  },
  "fetchedAt": "2026-10-05T12:00:00.000Z"
}

A video YouTube has no figures for in the window comes back with every metric null.

Errors — 401 unauthorized, 400 invalid_request, 404 account_not_found, 404 profile_not_found, 422 connection_expired, 422 provider_not_configured, 429 rate_limited, 502 provider_error.

Not available

Instagram media-level insights and Facebook per-post insights are not part of v1. TikTok and YouTube per-post insights are, above.