Skip to main content
Use Live for a current public profile, individual post, or feed page. Use managed tracking for saved accounts, recurring refreshes, historical metrics, and dashboard analytics. Live is on-demand retrieval, not streaming or a webhook subscription.

Access

Register and select an eligible workspace, then send its API key as Authorization: Bearer YOUR_API_KEY. Live uses the same access rules as the rest of v2:
  • Enterprise workspaces keep their existing access and terms. They do not need Stripe onboarding or a subscription.
  • Self-service workspaces need linked Stripe billing with an active subscription or an unexpired trial.
  • A valid read key can call Live; a write scope is not required. Missing or invalid keys return 401. Inactive keys or ineligible workspace access return 403.
See Authentication and Usage & billing. Live introduces no separate request charges or credit balance. Existing workspace terms still apply.

Choose an operation

All six operations use GET. Paths below include the /v2 base path. Profiles and feeds accept a handle, optionally prefixed with @, not a profile URL. Handles are normalized to lowercase. Post lookups require a canonical HTTPS URL: Instagram /p/{shortcode}/, /reel/{shortcode}/, or /tv/{shortcode}/; TikTok /@{handle}/video/{numeric_id}. Shortened links are not supported.
The Live Instagram and Live TikTok groups in the API reference show the exact parameters and response schemas. The generated reference is the source of truth.

Read a snapshot

Profile and post responses contain data and meta. Feeds also contain pagination.
  • data.type is live_profile or live_post. A Live resource has a native platform external_id string, not a CreatorAudit tracking UUID. Do not pass it to routes that require a tracked account or video ID.
  • Profile fields include username, name, description, follower_count, following_count, and profile_post_count.
  • Posts use account_username, description, create_time, uppercase media_type (IMAGE, VIDEO, or CAROUSEL), and flat counters such as like_count, comment_count, view_count, play_count, share_count, and saved_count.
  • A null counter means unknown, hidden, or unavailable. An observed zero remains 0. Do not replace unknown values with zero or infer one counter from another. profile_post_count is the platform’s counter, not the number of posts retrieved.
  • meta.fetched_at is the observation timestamp, not the post’s publication time or a guarantee that platform counters updated at that instant. meta.cached is always false. Read meta.warnings for completeness caveats.
  • Fields ending in _url_original are original platform media URLs. They may expire or be unavailable; they are not durable CreatorAudit-hosted media links.
Live does not enroll an account or post, save tracking metrics, copy media, or schedule future refreshes. It does not create dashboard history. Use POST /v2/accounts or POST /v2/videos explicitly if you want to start tracking.

Page through a feed

GET /v2/live/{platform}/posts returns one source-sized page. You cannot choose a page size with limit or request include_total. Its pagination object contains only next_cursor and has_next. Start with handle only. If pagination.has_next is true, send pagination.next_cursor unchanged as cursor with the same platform and normalized handle. Do not decode, edit, or reuse a cursor for another account. Invalid or mismatched cursors return 422. You can also follow the response’s Link header with rel="next".
Stop when has_next is false. A feed can be empty. Neither one page nor following every available cursor guarantees a complete account history; public availability and platform pagination determine what can be returned.

Cache, limits, and errors

All Live responses, including failures, use Cache-Control: no-store. They have no ETag and do not return 304 for conditional GETs. Do not apply the tracked-resource ETag polling examples to Live. Your workspace shares a budget of 60 admitted Live requests per rolling minute and two concurrent logical Live requests across all keys, platforms, and operations. Creating or rotating keys does not increase it. Enterprise access does not bypass these limits. They are process-local safeguards, not a fleet-wide quota or throughput guarantee. The regular per-key rate limit still applies; X-RateLimit-* headers describe that per-key limit, not the remaining Live organization budget.
  • 429 / RATE_LIMITED: honor Retry-After and reduce concurrency. A platform limit can also produce 429.
  • 404 / NOT_FOUND: the public profile or post is missing or unavailable. This does not prove it was deleted.
  • 422 / VALIDATION_ERROR: fix the handle, canonical URL, or cursor before retrying.
  • 502 / UPSTREAM_ERROR: the platform could not supply usable data.
  • 503 / SERVICE_UNAVAILABLE: retrieval is temporarily unavailable or shared capacity is full.
  • 504 / UPSTREAM_TIMEOUT: retrieval exceeded its deadline.
Use bounded retries with backoff for transient errors, honor Retry-After when supplied, and retain X-Request-ID for support. See Rate limits, Errors, and the Live code examples.