Skip to main content
All endpoints below require:
  • X-Application-Id
  • X-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.
Optional fields:
  • platform: INSTAGRAM, TIKTOK, YOUTUBE, FACEBOOK, or TWITTER
  • isAccount: explicitly identify an ambiguous URL as an account or post
  • captionFilter: account-only keyword, hashtag, mention, or phrase filter
  • trackRelativeValue and trackRelativeUnit: how long discovered posts are tracked after upload; use DAYS or MONTHS
  • collectionIds: collections to add the target to
  • forceScrape: 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.
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: accounts or posts; omit to return both
  • page: default 1
  • limit: default 20, maximum 100
  • q: 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. 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: default 1
  • limit: default 20, maximum 100

​
PATCH /sdk/v1/analytics/tracked-media/:trackedMediaId/track-window

Update tracking configuration.
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. 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.
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.

​
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: default 1
  • limit: default 20, maximum 100
  • q: collection-name search
  • kind: fixed or live

​
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.
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: default 1
  • limit: default 20, maximum 100
  • q: target URL search

​
POST /sdk/v1/analytics/collections/:collectionId/members

Add a tracked account or post to a collection.
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 filters are not available on the SDK surface. The exception is an automatically generated campaign collection selected with scope=collections: its saved campaign filter resolves the ongoing campaign’s media while preserving collection semantics. Common query parameters:
  • startDate and endDate: optional YYYY-MM-DD date range; defaults to the latest 30 days
  • platform: FACEBOOK, YOUTUBE, INSTAGRAM, TIKTOK, or TWITTER
  • collectionIds: comma-separated collection IDs
  • trackedMediaIds: comma-separated tracked post IDs
  • trackedAccountIds: comma-separated tracked account IDs; account IDs expand to their discovered posts
  • includeIncomplete: 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, or virality
  • mode: delta for change during each day or total for cumulative totals

​
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: videos or accounts
  • metric: supported analytics metric
  • mode: delta or total
  • limit: rows per page; default 20, maximum 100
  • page=1: start a paginated ranking
  • cursor: continue from the previous response’s pagination.nextCursor; omit page when 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 metric
  • mode: delta or total

​
GET /sdk/v1/analytics/video-lengths

Group post performance by video-duration bucket. Additional parameters:
  • metric: supported analytics metric
  • mode: delta or total
  • bucketPreset: optional; defaults to shortform_v1 (0-15s, 16-30s, 31-60s, 61-90s, 90s+). shortform_v2 splits 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:
  • startDate and endDate
  • metric
  • mode: delta or total

​
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.