Skip to content
ShortsIntel
Create a key

API referenceAds

List a TikTok Ad's snapshots

GET/v1/ads/tiktok/{ad_id}/snapshots

Every observation of the Ad, newest first. not_found until the Ad has been looked up or searched.

Open in Playground(no API Key needed)

Price

Free.

Parameters

NameInTypeRequiredDefaultDescription
ad_idpathstringRequired—The TikTok ad library id.
limitqueryintegermin 1; max 100Optional25Items per page.
cursorquerystringOptional—Opaque next_cursor from the previous page.

Responses

200 OK

{ items, next_cursor }.

object

  • itemsarray of objectrequired
    • atstringrequired
    • metricsanyMeta: running, placements, countries, variant_count, and spend, impressions and reach ranges with currency where disclosed. TikTok: running, last_shown, audience, countries, targeting.
    • sourcestringrequired
  • next_cursorstringrequirednullablePass back as cursor. Null on the last page.

200 · `{ items, next_cursor }`.

{
  "items": [
    {
      "at": "2026-10-23T09:12:58.104Z",
      "metrics": {
        "running": true,
        "last_shown": "2026-10-22T00:00:00.000Z",
        "audience": "100K-200K",
        "countries": null
      },
      "source": "vendor"
    }
  ],
  "next_cursor": null
}

400 Bad Request

invalid_request for a cursor that is not a next_cursor this API issued. Nothing is charged.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

  • typestringrequired
  • titlestringrequired
  • statusintegerrequired
  • codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
  • detailstring

400 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "`cursor` is not a cursor this API issued. Pass back the `next_cursor` from the previous page."
}

401 Unauthorized

missing_authorization, invalid_key, key_revoked or invalid_token.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

  • typestringrequired
  • titlestringrequired
  • statusintegerrequired
  • codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
  • detailstring

401 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/invalid_key",
  "title": "Invalid key",
  "status": 401,
  "code": "invalid_key",
  "detail": "That API key does not exist. Keys look like `sk_live_...` and are created in the console."
}

404 Not Found

not_found — including anything belonging to another Customer.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

  • typestringrequired
  • titlestringrequired
  • statusintegerrequired
  • codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
  • detailstring

404 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No such resource for this Customer."
}

Request samples

Use ShortsIntel to list a TikTok Ad's snapshots.

- ad_id: ad_id_example
- limit: 25

Tell me what it will cost before you run it, then summarise what you find.

If you don't have ShortsIntel tools, don't guess: tell me to connect it first. Add the MCP server https://www.shortsintel.com/api/mcp (or install the ShortsIntel plugin), sign in, and retry. Setup guide: https://www.shortsintel.com/docs/mcp
  • Pagination: Following next_cursor through a list.
  • Ads: Searching Meta's Ad Library with its filters, what each Ad carries, the winner Score, Ad analysis, what is stored, and how an ad search is priced.