All documentation
Documentation
All endpoints below require:
X-Application-IdX-Api-Key
Standalone analytics tracks social accounts and posts without adding them to a campaign. The API supports Instagram, TikTok, YouTube, Facebook, and X/Twitter URLs.
Paginated list endpoints accept page and limit, and return a top-level pagination object with page, limit, total, and totalPages. The /top ranking uses a continuation cursor and hasMore instead of totals; see below.
Track content
POST /sdk/v1/analytics/tracked-media
Track one account or post. Grade detects the platform and target type from the URL and schedules the first scrape.
{
"url": "https://www.tiktok.com/@creator/video/7350000000000000000",
"trackStartAt": "2026-07-01T00:00:00.000Z",
"collectionIds": ["collection_..."]
}
Optional fields:
platform:INSTAGRAM,TIKTOK,YOUTUBE,FACEBOOK, orTWITTERisAccount: explicitly identify an ambiguous URL as an account or postcaptionFilter: account-only keyword, hashtag, mention, or phrase filtertrackRelativeValueandtrackRelativeUnit: how long discovered posts are tracked after upload; useDAYSorMONTHScollectionIds: collections to add the target toforceScrape: request a manual retry when an existing target is already being tracked; the retry is subject to the manual refresh policy below
The response includes the trackedMediaId, normalized URL, tracking configuration, scrape state, and whether the row was created, restored, or already existed. Reposting an existing or previously deleted target does not schedule another scrape unless forceScrape is true. Forced refreshes remain subject to the manual refresh policy below.
POST /sdk/v1/analytics/tracked-media/bulk
Track up to 200 URLs in one request.
{
"urls": [
"https://www.instagram.com/creator/",
"https://www.youtube.com/shorts/abc123xyz"
],
"captionFilter": "#gradepartner",
"collectionIds": ["collection_..."]
}
The response contains a result for each URL and a summary of created, existing, restored, duplicate, and failed items. Existing targets are not rescraped by the bulk endpoint.
Manage tracked content
GET /sdk/v1/analytics/tracked-media
List standalone tracked targets.
Query parameters:
type:accountsorposts; omit to return bothpage: default1limit: default20, maximum100q: URL or normalized-target search
Account rows include metrics aggregated across discovered posts. Post rows include their latest views, likes, comments, and shares, plus bookmarks (null or 0 until the first tracking snapshot lands; platforms that do not report bookmarks always read 0) and durationSeconds (null when the actor supplied no length). Every row includes scrape state and issue information.
Account media rows include accountIssue, independently of tracking tier. It is null when no warning is recorded, including before the first check. A successful completed check clears it. Do not render an “OK” badge or treat null as proof that all historical posts were discovered.
{
"accountIssue": {
"code": "CHECK_FAILED",
"reasonCode": "INCOMPLETE_RESPONSE",
"message": "The provider did not finish retrieving this account.",
"checkedAt": "2026-10-19T04:05:00.000Z"
}
}
| Code | Meaning |
|---|---|
PROFILE_NOT_FOUND |
The provider explicitly reported that the profile does not exist. Check its link or username. |
PROFILE_PRIVATE |
The provider explicitly identified a private profile. |
NO_ACCESSIBLE_VIDEOS |
No public posts could be retrieved. This may include a login wall; it does not prove the creator has never posted. |
CHECK_FAILED |
The check could not finish reliably. Use reasonCode and message to explain why. |
CHECK_FAILED reasons are ACCESS_BLOCKED, RATE_LIMITED, TIMEOUT, INCOMPLETE_RESPONSE, INVALID_RESPONSE, PROCESSING_FAILED, PROFILE_UNAVAILABLE, PROVIDER_UNAVAILABLE, and PROVIDER_ERROR. Other codes have a null reason. PROCESSING_FAILED identifies a Grade-side failure to prepare the check or process its results, including an invalid account target or missing tracking dates. Messages are safe for display; use codes for application logic.
checkedAt is the UTC time of the reported issue. The previous warning remains while a new check is pending. An empty date-filtered window is not an account warning, and a failed individual post does not label its parent account missing or private. Results are scoped to each account, including when several accounts share a provider run. Providers include Apify actors and the official X API.
Temporary CHECK_FAILED results remain internal while automatic recovery is pending. If recovery succeeds, no new warning appears. If recovery finishes unsuccessfully, Grade publishes the issue and its reason. Failures with no remaining automatic recovery can be published immediately. Explicit profile availability responses do not wait for technical retries.
The official X API continues retrying without a fixed attempt limit. Its first transient failure stays internal; a subsequent failure at least three hours later publishes CHECK_FAILED if the account check still has not completed. Retries continue, and a successful completed check clears the warning.
Instagram account checks combine the required posts and reels providers. Neither provider can clear a warning while the other is pending or recovering. Conflicting availability responses become CHECK_FAILED with INCOMPLETE_RESPONSE; Grade does not assert that a profile is private or missing when another required provider succeeds. A successful posts check with no accessible reels does not itself produce a warning.
Tracked-media rows also expose normalized content metadata when the platform actor supplies it:
- Author:
authorPlatformId,authorUsername,authorDisplayName - Content:
title,captionText,hashtags - Audio:
audioPlatformId,audioTitle,audioArtist,audioAlbum,audioIsOriginal - Freshness:
metadataCollectedAt
Unavailable actor fields are null; hashtags is an empty array when none are available. These fields are returned by the tracked-media list, detail, and discovered-post endpoints. They also appear on the nested trackedMedia object returned for collection members, on tracked video results from /top, and in data.meta from /media/tracked/:trackedMediaId.
GET /sdk/v1/analytics/tracked-media/:trackedMediaId
Get one tracked account or post with its latest metrics and asOfTimestamp.
GET /sdk/v1/analytics/tracked-media/:trackedMediaId/posts
List posts discovered from a tracked account.
Query parameters:
page: default1limit: default20, maximum100
PATCH /sdk/v1/analytics/tracked-media/:trackedMediaId/track-window
Update tracking configuration.
{
"captionFilter": "#gradepartner",
"trackRelativeValue": 30,
"trackRelativeUnit": "DAYS"
}
You can also update trackStartAt. Send trackRelativeValue: null and trackRelativeUnit: null together to clear the relative window. captionFilter is only valid for accounts.
POST /sdk/v1/analytics/tracked-media/:trackedMediaId/scrape-now
Request an immediate scrape. Scrape execution is asynchronous.
This endpoint accepts standalone trackedMediaId values. For campaign accounts
or posts, use campaign media refresh
with the campaignCreatorMediaId instead.
Manual refreshes use the same policy as campaign media: each tracked target can be refreshed up to three times, with a four-hour cooldown after each successfully queued refresh. A target in its cooldown returns 429 with Retry-After, refreshAvailableAt, and refreshCooldownMs. A target that has used all three refreshes returns 409 with code ATM_REFRESH_LIMIT_REACHED.
PATCH /sdk/v1/analytics/tracked-media/:trackedMediaId/tracking-tier
Wake a sleeping target.
{
"trackingTier": 1
}
Already-active targets return a successful no-op response.
DELETE /sdk/v1/analytics/tracked-media/:trackedMediaId
Stop tracking a target. Deleting an account also soft-deletes its discovered child posts.
Collections
POST /sdk/v1/analytics/collections
Create a collection.
{
"name": "Summer creators"
}
GET /sdk/v1/analytics/collections
List collections with account/video counts and current views, likes, comments, and shares.
Every ongoing campaign is also returned as an automatically generated live collection. These records have kind: "live", automaticallyGenerated: true, and a campaignId. Their counts and metrics follow the campaign automatically, including when the request is made through the SDK. Completed and deleted campaigns are not returned.
Query parameters:
page: default1limit: default20, maximum100q: collection-name searchkind:fixedorlive
GET /sdk/v1/analytics/collections/:collectionId
Resolve a collection by ID. The response includes kind, filterQuery, surface, campaignId, and automaticallyGenerated so clients can distinguish fixed, user-authored live, and campaign-generated collections.
PATCH /sdk/v1/analytics/collections/:collectionId
Rename a collection.
{
"name": "Updated collection name"
}
Automatically generated campaign collections are read-only. Rename, filter update, freeze, delete, and membership mutations return 409 Conflict; update the campaign instead.
DELETE /sdk/v1/analytics/collections/:collectionId
Delete a collection and its member associations. This does not delete the tracked media itself.
Collections that also contain campaign members cannot be deleted through the standalone analytics API and return 409 Conflict. Automatically generated campaign collections are also managed by the campaign and cannot be deleted directly.
GET /sdk/v1/analytics/collections/:collectionId/members
List materialized standalone tracked accounts and posts in a fixed collection. Live collections compute their scope from their saved filter and do not create membership rows.
Query parameters:
page: default1limit: default20, maximum100q: target URL search
POST /sdk/v1/analytics/collections/:collectionId/members
Add a tracked account or post to a collection.
{
"trackedMediaId": "atm_..."
}
Adding an existing membership succeeds with meta.duplicate: true.
DELETE /sdk/v1/analytics/collections/:collectionId/members/:memberId
Remove a tracked member from a collection without stopping its tracking.
Query analytics
Analytics endpoints default to scope=tracked. Direct campaign scopes require both analytics:read and campaigns:read: use scope=campaign or campaigns with campaignId/campaignIds, scope=creator or creators with creatorProfileId/creatorProfileIds, or scope=media with campaignCreatorMediaId. scope=collections retains its collection behavior, including automatically generated campaign collections. All identifiers are scoped to the API key's agency.
Common query parameters:
startDateandendDate: optionalYYYY-MM-DDdate range; defaults to the latest 30 daysplatform:FACEBOOK,YOUTUBE,INSTAGRAM,TIKTOK, orTWITTERcollectionIds: comma-separated collection IDstrackedMediaIds: comma-separated tracked post IDstrackedAccountIds: comma-separated tracked account IDs; account IDs expand to their discovered postsincludeIncomplete: include the current incomplete day
You can combine collection and tracked-ID filters. IDs are always scoped to the agency associated with the SDK application.
For /summary, /series, and /top, pass includeHidden=false to stop counting a currently hidden campaign creator's performance at their saved hide date. This applies to campaign media included through campaign-generated collections. Standalone tracked media is unaffected. Omitting the parameter or passing includeHidden=true keeps the existing behavior, including all snapshots.
The last available snapshot at or before hidden_at is used: earlier contributions remain, cumulative totals freeze, and subsequent growth is zero. This uses the one current hide date, without reconstructing past hide/unhide periods. Unhiding removes the cutoff; hiding again sets a new date. A legacy hidden creator without a saved date contributes no snapshots with this option. Existing stored snapshots are used, so no backfill is required.
GET /sdk/v1/analytics/summary
Return views, likes, comments, shares, bookmarks, engagements, engagement rate, virality, videos tracked, active accounts, and growth comparisons.
GET /sdk/v1/analytics/series
Return daily values for one metric.
Additional parameters:
metric:views,likes,comments,shares,bookmarks,engagements,engagement_rate, orviralitymode:deltafor change during each day ortotalfor cumulative totals
Daily growth excludes catch-up increments from confirmed administrative resets when the preceding observation was at least 30 days before the reset request. Only the first successful refresh increment is excluded; later growth still counts. Ordinary gaps in observations are unchanged. The same exclusion applies to single-day delta rankings and summaries. Lifetime totals and payment calculations are unchanged. Multi-day net snapshot comparisons retain their existing definition and may exceed the sum of daily growth values.
GET /sdk/v1/analytics/top
Rank videos or accounts in the selected scope, including campaign media from campaign-generated collections.
Tracked video results include the normalized author, content, hashtag, and audio fields described above. Tracked account results include available author identity fields and metadataCollectedAt.
Additional parameters:
type:videosoraccountsmetric: supported analytics metricmode:deltaortotallimit: rows per page; default20, maximum100page=1: start a paginated rankingcursor: continue from the previous response'spagination.nextCursor; omitpagewhen supplying a cursor
Start with page=1&limit=100. The response includes pagination: { "page": 1, "limit": 100, "hasMore": true, "nextCursor": "..." }. For the next request, replace page with cursor=<nextCursor>, keeping the other filters and limit unchanged. Continue until hasMore is false and nextCursor is null. There is no total-results cap. Direct jumps such as page=100000 are rejected; each request fetches at most 101 candidates per source.
Omitting both page and cursor preserves the existing response shape. Equal metric values use a stable ID tie-break. Rankings remain live; restart with page=1 if campaign membership, visibility, or filters change during pagination.
First request: /sdk/v1/analytics/top?scope=collections&collectionIds=ACOLL_CAMP_123&type=videos&metric=views&mode=delta&includeHidden=false&page=1&limit=100.
Next request: /sdk/v1/analytics/top?scope=collections&collectionIds=ACOLL_CAMP_123&type=videos&metric=views&mode=delta&includeHidden=false&cursor=<nextCursor>&limit=100.
GET /sdk/v1/analytics/posting-activity
Return the number of posts published on each date, including account coverage metadata.
GET /sdk/v1/analytics/posting-schedule
Group publishing performance by day of week and hour.
Additional parameters:
metric: supported analytics metricmode:deltaortotal
GET /sdk/v1/analytics/video-lengths
Group post performance by video-duration bucket.
Additional parameters:
metric: supported analytics metricmode:deltaortotalbucketPreset: optional; defaults toshortform_v1(0-15s,16-30s,31-60s,61-90s,90s+).shortform_v2splits the open tail at three minutes (91-180s,180s+), the point where YouTube Shorts and Instagram Reels stop counting as short-form.
Each post contributes one observation to the bucket matching its positive whole-second duration. The bucket value is the exact median across posts with an available metric result; posts without an in-range tracking observation or usable metric denominator are excluded from both the median and post count.
engagement_rate and virality are always evaluated in total (lifetime) mode for this endpoint. The chart cohort is posts uploaded inside the selected date range, so a pre-range baseline generally does not exist for a truthful delta rate. If a client requests mode=delta for either metric, the response reports meta.mode: "total", meta.requestedMode: "delta", and meta.modeAdjusted: true. Other metrics preserve the requested mode. Virality values are shares per 1,000 views, not percentages.
GET /sdk/v1/analytics/media/tracked/:trackedMediaId
Return the date-range summary and daily series for one tracked post. data.meta includes the normalized author, content, hashtag, audio, and metadata-freshness fields described above.
Optional query parameters:
startDateandendDatemetricmode:deltaortotal
Metric freshness
Analytics responses include meta.asOfTimestamp. This is the latest stored tracking snapshot used by the response and may be null before the first scrape completes.
Metric availability differs by platform. Responses include availability metadata when a metric is unsupported or only partially supported across the selected targets.
Campaign-media detail
GET /sdk/v1/analytics/media/campaign/:campaignCreatorMediaId requires analytics:read and campaigns:read. It supports the same date range and aggregation options as tracked-media detail.
Bulk collection membership and freezing
POST /sdk/v1/analytics/collections/:collectionId/members/bulk requires analytics:write:
{ "trackedMediaIds": ["tracked-id"], "campaignCreatorMediaIds": ["campaign-media-id"] }
The combined maximum is 1000 unique IDs per call. All IDs must belong to the agency. Campaign IDs additionally require campaigns:read; send an empty trackedMediaIds array when adding only campaign media. Duplicate members are counted as already present. The response includes requestedCount, addedCount, and alreadyPresentCount.
Collection and member lists still default to standalone content. Pass source=all with both analytics:read and campaigns:read to include campaign members. Keys with campaigns:read may also remove campaign members or delete a mixed collection with analytics:write.
To freeze a live collection, first harvest the desired members through the bulk endpoint with forFreeze: true. After every batch succeeds, call POST /sdk/v1/analytics/collections/:collectionId/freeze with {}. This requires analytics:write and converts the saved filter to a fixed list using the members already written. Freeze does not harvest rows automatically. The conversion has no undo; create a new live collection to use a filter again. Automatically generated collections cannot be modified or frozen.
