{ "openapi": "3.1.0", "info": { "title": "SocialCrawl API: TikTok", "version": "1.0.0", "description": "Unified social media data API - one API key, one consistent response format, 69 platforms, 678 endpoints. Power AI agents with clean social data.\n\nThis document covers the TikTok endpoints only (38 operations). The full contract for every platform is at https://www.socialcrawl.dev/v1/openapi.json, and every per-platform document is listed at https://www.socialcrawl.dev/openapi/index.json.", "contact": { "name": "SocialCrawl", "url": "https://www.socialcrawl.dev", "email": "socialcrawl@ridio.io" } }, "servers": [ { "url": "https://www.socialcrawl.dev/v1", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key authentication. Send your key in the `x-api-key` request header on every call. Create and manage keys in the dashboard." }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "The same API key sent as `Authorization: Bearer `, the default in most agents and HTTP tools. Same key, same rules; when both headers are sent, `x-api-key` wins." } }, "schemas": { "ErrorEnvelope": { "type": "object", "description": "Unified error response envelope. Every 4xx/5xx response returns this shape; `error.type` is a machine-readable code from the API's error catalog.", "properties": { "success": { "type": "boolean", "enum": [ false ], "example": false, "description": "Always false on an error response." }, "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "MISSING_API_KEY", "INVALID_API_KEY", "INSUFFICIENT_CREDITS", "INVALID_REQUEST", "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "CONCURRENCY_LIMIT", "UPSTREAM_ERROR", "SERVICE_UNAVAILABLE", "INTERNAL_ERROR", "METHOD_NOT_ALLOWED", "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "COHORT_RESULT_TOO_LARGE", "PAYLOAD_TOO_LARGE", "RATE_LIMITED", "KEY_BUDGET_EXCEEDED", "RUN_NOT_FOUND", "RUN_STATE_CONFLICT", "RUN_EXPIRED", "NEEDS_ASYNC", "CURSOR_EXPIRED", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND", "STREAM_STATE_CONFLICT" ], "example": "INVALID_REQUEST", "description": "Machine-readable error code. The per-status `x-error-codes` list on each response narrows which codes that status can carry." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "status": { "type": "integer", "description": "HTTP status code, echoed in the body." }, "doc_url": { "type": "string", "description": "Link to the docs page for this error code." }, "retryable": { "type": "boolean", "description": "Whether retrying the identical request can succeed. True for rate limits, concurrency limits, idempotency contention and transient upstream or server failures; false for every other code, including both 402s." }, "details": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Optional structured context. Omitted on ordinary errors. Both 402s carry `reason` (`balance_too_low` or `key_budget_reached`), `retry_will_succeed: false`, a one-sentence `next_step`, and `top_up_url` or `key_settings_url`; the GET endpoints add `credits_required`; a metered endpoint adds `pricing` (`\"ceiling\"` when the hold is the most the call can cost and the unused part is refunded, `\"exact\"` when the call is charged what it holds; measured on recent production calls), `credits_typical` (on a ceiling, what a call like this is usually charged), and, when a cheaper shape of the same request exists, `lower_cost_with`, `lower_cost_options` (`param`, `value` or null to leave it out, and `credits_required` with that change) and `credits_required_cheapest`. A `max_credits` page that switched to a cheaper form to fit (`threads/search` with `expand=false`) and still found the balance short adds `balance_fallback`: the `param` and `value` it switched to, and `credits_required` for the call as sent. A page-cap rejection carries `reason: \"page_limit\"` with `max_page`, `requested_page` and `narrow_with`. An `INVALID_REQUEST` that sends no member of a required one-of group carries `fields` (the parameters of that group) and a one-sentence `next_step`. Other endpoints use it for their own taxonomies, such as the comment-lookup not-found reasons." }, "status_url": { "type": "string", "format": "uri", "description": "Present on 5xx responses: the public status page, filtered to the platform when one is known." }, "incident": { "type": "object", "description": "Present on a 5xx response when an open public incident explains the failure.", "properties": { "id": { "type": "string", "example": "k3v9w2m8q1zt" }, "title": { "type": "string" }, "status": { "type": "string", "example": "investigating" }, "impact": { "type": "string", "example": "major" }, "url": { "type": "string", "format": "uri" } }, "required": [ "id", "title", "status", "impact", "url" ] } }, "required": [ "type", "message", "status", "doc_url" ] }, "credits_used": { "type": "integer", "description": "Net credits charged for this request. Error paths deduct-then-refund, so this is 0 in almost every case; a partial-coverage composite may keep the succeeded-leg cost." }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Credits left after this request when established. Some unauthenticated errors use null; on a prebilling route whose attempted balance lookup fails, this field is omitted instead of fabricated." }, "request_id": { "type": "string", "description": "Unique request identifier - matches the X-Request-Id header. Quote it in support requests." } }, "required": [ "success", "error", "credits_used", "request_id" ] }, "MonitorAlertRule": { "description": "A numeric condition evaluated against a monitor run and, for change operators, a previous comparable run.", "properties": { "metric": { "description": "Dot path to a numeric key in the recipe's own result, for example `coverage` or `summary.total`. On a numbers-only monitor (created with `track`) the metric must be one of `track.metrics`, and an `items[].` metric is evaluated once per row: a fired alert then carries `row_id`. The special metric `rows_new` (numbers-only monitors only; it needs an `items[].` metric in `track.metrics` and is not itself tracked) counts the list rows this run has that the previous run did not: `{\"metric\":\"rows_new\",\"op\":\"gt\",\"value\":0}` alerts on any new post or video. It accepts only `gt` and `gte`, and is skipped on the first run. \"New\" means absent from the previous successful run's stored rows (capped at `max_rows`, default 100), so a row that drops off and returns later counts as new again. An empty-page run is refunded and is not a baseline, so on a sparse feed the first run that holds rows has no baseline and stays silent: the first new post after a quiet period may not alert. Use a daily cadence or leave `max_rows` headroom.", "type": "string" }, "op": { "enum": [ "gt", "lt", "gte", "lte", "abs_change_gt", "pct_change_gt", "pct_change_lt" ], "type": "string" }, "value": { "type": "number" }, "window": { "description": "Accepted and stored, but ignored: a change op always compares against the immediately preceding comparable run, whatever the value.", "enum": [ "1d", "1w" ], "type": "string" } }, "required": [ "metric", "op", "value" ], "type": "object" }, "EventEnvelope": { "description": "One event, identical in the feed and in every webhook batch. `id` is stable for one fact, so deduplicate on it.", "properties": { "id": { "description": "Deterministic event id: the same fact never mints a second event.", "example": "evt_k3m7q2xwcbvd4nph6trz5ycgda", "type": "string" }, "type": { "description": "Dot-delimited lower-case type. Types written today: `discover.progress`, `discover.accounts_ready`, `discover.completed`, `discover.partial`, `discover.paused`, `discover.failed`, `discover.new_rows`, `discover.new_accounts`, `discover.new_items`, `discover.run_skipped`, `discover.run_failed`, `endpoint.disabled`, `mention.created`, `mention.deleted`, `stream.baseline.established`, `stream.coverage_gap`, `stream.paused`, `stream.resumed`, `stream.deleted`, `stream.budget.warning`, `stream.health`.", "example": "discover.completed", "type": "string" }, "api_version": { "example": "2026-10-01", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "cursor": { "description": "The feed position right after this event. Send it as `cursor` to read what came after; an event id works too.", "example": "c_MS4xMi4xNzkyNDA0OTA0", "type": "string" }, "subject": { "description": "The object the event is about, for example `{ kind: \"discover_run\", id: \"run_…\" }`.", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "metadata": { "type": [ "object", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "kind", "id" ], "type": [ "object", "null" ] }, "data": { "description": "The event's facts. Discover events carry counts and ids, never keywords or row text.", "type": "object" }, "links": { "additionalProperties": { "type": "string" }, "description": "Absolute URLs to the subject, such as `run` and `results` (for example `https://www.socialcrawl.dev/v1/prism/discover/runs/run_...`), the same in the feed and in webhook batches. Events served before 26/10/2026 carried relative paths.", "type": "object" } }, "required": [ "id", "type", "api_version", "created_at", "cursor", "subject", "data", "links" ], "type": "object" }, "WebhookEndpoint": { "description": "A registered receiver. The signing secret is never part of it: it is returned once, by create and by rotate-secret.", "properties": { "id": { "example": "we_V1StGXR8Z5jdHi6BmyT", "type": "string" }, "url": { "example": "https://example.com/hooks/socialcrawl", "type": "string" }, "description": { "type": [ "string", "null" ] }, "types": { "description": "Subscribed event types: exact types, `ns.*` wildcards, or `*` for every type.", "items": { "type": "string" }, "type": "array" }, "subject_ids": { "description": "Only events about these subjects (a run or schedule id); null for every subject.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "status": { "enum": [ "enabled", "disabled" ], "type": "string" }, "disabled_reason": { "description": "`gone` (the receiver answered 410), `failing` (5 consecutive days of failed deliveries), `key_revoked` (the creating key was revoked or deleted) or `user` (set with PATCH). Null while enabled.", "enum": [ "gone", "failing", "key_revoked", "user", null ], "type": [ "string", "null" ] }, "failing_since": { "description": "Start of the current run of failed deliveries; null while healthy.", "format": "date-time", "type": [ "string", "null" ] }, "api_version": { "example": "2026-10-01", "type": "string" }, "secret_rotation": { "description": "Set during a rotation: until `previous_secret_expires_at` every delivery is signed with both secrets.", "properties": { "previous_secret_expires_at": { "format": "date-time", "type": "string" } }, "type": [ "object", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "next": { "description": "Ready relative URLs for the next calls.", "properties": { "attempts_url": { "type": "string" }, "events_url": { "type": "string" }, "rotate_secret_url": { "type": "string" }, "self_url": { "type": "string" }, "test_url": { "type": "string" } }, "type": "object" } }, "required": [ "id", "url", "types", "status", "api_version", "created_at" ], "type": "object" }, "WebhookAttempt": { "description": "One delivery attempt. `response_excerpt` is at most 1 KB of your receiver's answer.", "properties": { "id": { "type": "string" }, "delivery_id": { "description": "The batch's `webhook-id`, the same on every retry.", "type": "string" }, "test": { "type": "boolean" }, "status": { "description": "Your receiver's HTTP status; null for a timeout, a refused host, a network error or a secret that could not be opened.", "type": [ "integer", "null" ] }, "outcome": { "enum": [ "delivered", "failed", "gone", "retry_after", "timeout", "redirect", "refused_host", "secret_unavailable", "network_error" ], "type": "string" }, "duration_ms": { "type": [ "integer", "null" ] }, "response_excerpt": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "delivery_id", "test", "status", "outcome", "created_at" ], "type": "object" }, "EventBatch": { "description": "What every delivery carries, also for one event: at most 100 events or 256 KB. Each inner event keeps its own `id` and `cursor`; deduplicate on the inner ids. A test send marks its event `\"test\": true` with `\"cursor\": null`.", "properties": { "id": { "example": "bat_V1StGXR8Z5jdHi6BmyT", "type": "string" }, "type": { "const": "event.batch", "type": "string" }, "data": { "properties": { "events": { "items": { "$ref": "#/components/schemas/EventEnvelope" }, "maxItems": 100, "type": "array" } }, "required": [ "events" ], "type": "object" } }, "required": [ "id", "type", "data" ], "type": "object" }, "ListeningRuleAst": { "description": "A rule as a tree of `and`, `or`, `not`, `term`, `phrase` and `field` nodes, as the dry run returns it in `data.stream.groups[].ast`.", "anyOf": [ { "type": "object", "properties": { "and": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/ListeningRuleAst" } } }, "required": [ "and" ], "additionalProperties": false }, { "type": "object", "properties": { "or": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/ListeningRuleAst" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "not": { "$ref": "#/components/schemas/ListeningRuleAst" } }, "required": [ "not" ], "additionalProperties": false }, { "type": "object", "properties": { "term": { "type": "string", "minLength": 1 } }, "required": [ "term" ], "additionalProperties": false }, { "type": "object", "properties": { "phrase": { "type": "string", "minLength": 1 } }, "required": [ "phrase" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "lang", "country", "platform", "site", "community" ] }, "value": { "type": "string", "minLength": 1 } }, "required": [ "field", "value" ], "additionalProperties": false } ] } } }, "tags": [ { "name": "tiktok", "description": "Tiktok endpoints" } ], "paths": { "/tiktok/profile": { "get": { "summary": "Get TikTok user profile", "description": "Returns public profile information for a TikTok user: follower count, following count, total likes, bio, avatar URL, verification status, and the ISO 3166-1 alpha-2 region of the account at `author.location` (the same leaf `/v1/tiktok/profile/region` returns, included here so you do not need a second call). `author.followers` is the unrounded integer when the source exposes it. When only the public rounded figure is available, the same integer field is returned and `author.ext.followers_approximate` is true. Pass either `handle` or `user_id`. Profiles behind TikTok's 'audience controls' (a login/age wall in the browser) now return their profile record normally; their posts are readable through `/v1/tiktok/profile/videos` with the same handle. A profile with no publicly readable record still returns `404 RESOURCE_NOT_FOUND` with `error.details.reason` set to `account_private`. A handle the platform reports as unused returns the same status with `reason` set to `account_gone`; because TikTok numeric ids are permanent, re-running the lookup with `user_id` tells a renamed account from a removed one. `author.location` can be absent when the region source is unavailable; the rest of the profile is still returned. TikTok keeps two live sets of profile counters, one for its app and one for its website (`statsV2`), and they can differ by a few percent in either direction. `author.followers`, `author.following`, `author.likes_count` and `author.posts_count` come from the app set by default; send `counts=web` to get the website set instead, at the same price. `author.ext.counts_source` names the set a response carries (`app` or `web`); a `counts=web` call answers with `app` when the website record could not be read.", "tags": [ "tiktok" ], "operationId": "get_tiktok_profile", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-socialcrawl-oneOf": [ [ "handle", "user_id" ] ], "parameters": [ { "name": "handle", "in": "query", "required": false, "description": "TikTok username without the @ symbol. (one of: handle, user_id; at least one required)", "schema": { "type": "string" }, "example": "charlidamelio" }, { "name": "user_id", "in": "query", "required": false, "description": "TikTok numeric user ID. Use this for faster responses. (one of: handle, user_id; at least one required)", "schema": { "type": "string" } }, { "name": "counts", "in": "query", "required": false, "description": "`app` (default) or `web`. `web` returns the follower, following, likes and video counts TikTok's website shows (`statsV2` `followerCount`, `followingCount`, `heartCount`, `videoCount`) in place of the app's counters. Same price. `author.ext.counts_source` confirms which set was returned.", "schema": { "type": "string", "enum": [ "app", "web" ] } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/profile" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "id": { "type": "string", "description": "Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)" }, "username": { "type": [ "string", "null" ], "description": "User handle or username" }, "display_name": { "type": [ "string", "null" ], "description": "Display name or full name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to profile picture" }, "bio": { "type": [ "string", "null" ], "description": "Profile biography or description" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the account is verified" }, "followers": { "type": [ "integer", "null" ], "description": "Follower or subscriber count as an integer. Exact on Instagram and on TikTok when the source exposes an unrounded figure. YouTube above 1,000 subscribers is YouTube's published three-significant-figure figure. When the integer is a published/rounded value, `author.ext.followers_approximate` is true." }, "following": { "type": [ "integer", "null" ], "description": "Number of accounts followed" }, "posts_count": { "type": [ "integer", "null" ], "description": "Total number of posts / videos / tracks / episodes" }, "likes_count": { "type": [ "integer", "null" ], "description": "Total likes received across the author's content (when surfaced)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the profile page" }, "location": { "type": [ "string", "null" ], "description": "ISO region code (e.g. `US`) or freeform location string when surfaced" }, "external_url": { "type": [ "string", "null" ], "description": "Bio link / external website URL when surfaced by the platform" }, "private": { "type": [ "boolean", "null" ], "description": "Boolean at author.private" }, "joined_at": { "type": [ "string", "null" ], "description": "String at author.joined_at" }, "last_post_at": { "type": [ "string", "null" ], "description": "String at author.last_post_at" }, "ext": { "type": [ "object", "null" ], "description": "Nested object: author.ext", "properties": { "social_context": { "type": [ "string", "null" ], "description": "String at author.ext.social_context" }, "account_created": { "type": [ "string", "null" ], "description": "String at author.ext.account_created" }, "country": { "type": [ "string", "null" ], "description": "String at author.ext.country" }, "country_name": { "type": [ "string", "null" ], "description": "String at author.ext.country_name" }, "collects_received": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.collects_received" }, "former_usernames": { "type": [ "array", "null" ], "description": "Array at author.ext.former_usernames", "items": { "type": "string", "description": "String at author.ext.former_usernames" } }, "former_usernames_count": { "type": [ "integer", "null" ], "description": "Instagram profile/about: how many former usernames Instagram's \"About this account\" panel lists for the account. 0 when the panel lists none, null when the panel could not be read on this call (the response then carries a note saying so). A count above 0 means the handle was renamed at least once; the names themselves are not published." }, "verified_at": { "type": [ "string", "null" ], "description": "Instagram profile/about, opt-in (`include=verified_at`): the month Instagram verified the account, as the panel shows it (\"April 2024\"). A month, not a date. Null when the account is not verified or the panel shows no verification date. Absent unless requested." }, "public_email": { "type": [ "string", "null" ], "description": "String at author.ext.public_email" }, "contact_email": { "type": [ "string", "null" ], "description": "Opt-in (`contact_email=1` on instagram/profile, youtube/channel and youtube/channel/about). When the bio lists two or more email addresses, the one the creator gives for contacting them personally, copied verbatim. Null when there is one address or none, when every address belongs to a manager, agency or brand, or when the choice was not confident. `author.ext.public_email` (the first address in the bio) is unchanged." }, "public_phone": { "type": [ "string", "null" ], "description": "String at author.ext.public_phone" }, "similar_source": { "type": [ "string", "null" ], "description": "String at author.ext.similar_source" }, "instagram_username": { "type": [ "string", "null" ], "description": "String at author.ext.instagram_username" }, "similar_via": { "type": [ "string", "null" ], "description": "String at author.ext.similar_via" }, "business_category": { "type": [ "string", "null" ], "description": "String at author.ext.business_category" }, "bio_links": { "type": [ "array", "null" ], "description": "Array at author.ext.bio_links", "items": { "type": "object", "description": "Nested object: author.ext.bio_links", "properties": { "title": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.title" }, "url": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.url" }, "link_type": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.link_type" } } } }, "is_business": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_business" }, "is_professional": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_professional" }, "creator_marketplace": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.creator_marketplace" }, "verification_label": { "type": [ "string", "null" ], "description": "String at author.ext.verification_label" }, "fbid": { "type": [ "string", "null" ], "description": "String at author.ext.fbid" }, "hd_avatar_url": { "type": [ "string", "null" ], "description": "String at author.ext.hd_avatar_url" }, "website": { "type": [ "string", "null" ], "description": "String at author.ext.website" }, "cover_url": { "type": [ "string", "null" ], "description": "String at author.ext.cover_url" }, "page_active": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.page_active" }, "employee_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.employee_count" }, "employee_count_range": { "type": [ "object", "null" ], "description": "Nested object: author.ext.employee_count_range", "properties": { "start": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.employee_count_range.start" }, "end": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.employee_count_range.end" } } }, "founded_year": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.founded_year" }, "company_type": { "type": [ "string", "null" ], "description": "String at author.ext.company_type" }, "tagline": { "type": [ "string", "null" ], "description": "String at author.ext.tagline" }, "specialities": { "type": [ "array", "null" ], "description": "Array at author.ext.specialities", "items": { "type": "string", "description": "String at author.ext.specialities" } }, "industries": { "type": [ "array", "null" ], "description": "Array at author.ext.industries", "items": { "type": "string", "description": "String at author.ext.industries" } }, "headquarters": { "type": [ "string", "null" ], "description": "Leaf at author.ext.headquarters" }, "locations": { "type": [ "array", "null" ], "description": "Array at author.ext.locations", "items": { "type": "string", "description": "Leaf at author.ext.locations" } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at author.ext.hashtags", "items": { "type": "string", "description": "Leaf at author.ext.hashtags" } }, "funding": { "type": [ "string", "null" ], "description": "Leaf at author.ext.funding" }, "address": { "type": [ "string", "null" ], "description": "String at author.ext.address" }, "price_range": { "type": [ "string", "null" ], "description": "String at author.ext.price_range" }, "rating": { "type": [ "string", "null" ], "description": "String at author.ext.rating" }, "rating_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.rating_count" }, "talking_about_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.talking_about_count" }, "business_hours": { "type": [ "array", "null" ], "description": "Array at author.ext.business_hours", "items": { "type": "string", "description": "Leaf at author.ext.business_hours" } }, "links": { "type": [ "array", "null" ], "description": "Array at author.ext.links", "items": { "type": "string", "description": "Leaf at author.ext.links" } }, "ad_library_page_id": { "type": [ "string", "null" ], "description": "String at author.ext.ad_library_page_id" }, "ad_library_status": { "type": [ "string", "null" ], "description": "String at author.ext.ad_library_status" }, "urn": { "type": [ "string", "null" ], "description": "String at author.ext.urn" }, "is_top_voice": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_top_voice" }, "is_premium": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_premium" }, "is_creator": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_creator" }, "is_influencer": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_influencer" }, "is_open_to_work": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_open_to_work" }, "is_hiring": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_hiring" }, "member_id": { "type": [ "string", "null" ], "description": "String at author.ext.member_id" }, "company_id": { "type": [ "string", "null" ], "description": "String at author.ext.company_id" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at author.ext.reaction_type" }, "followers_approximate": { "type": [ "boolean", "null" ], "description": "True when `author.followers` is a published or rounded figure rather than an unrounded census: LinkedIn people-list display buckets, TikTok `stats.followerCount` when the exact sibling is absent, and YouTube subscriber counts at or above 1,000. Null or absent on exact counts." }, "counts_source": { "type": [ "string", "null" ], "description": "TikTok profile only. Which of TikTok's two live counter sets `author.followers`, `author.following`, `author.likes_count` and `author.posts_count` carry: `app` (TikTok's app counters, the default) or `web` (the website's `statsV2`, returned with `counts=web`). The two sets can differ by a few percent in either direction." }, "keywords": { "type": [ "string", "null" ], "description": "String at author.ext.keywords" }, "total_views": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.total_views" }, "joined_at_timestamp": { "type": [ "string", "null" ], "description": "String at author.ext.joined_at_timestamp" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at author.ext.topicCategories", "items": { "type": "string", "description": "String at author.ext.topicCategories" } }, "bannerExternalUrl": { "type": [ "string", "null" ], "description": "String at author.ext.bannerExternalUrl" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.madeForKids" }, "hiddenSubscriberCount": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.hiddenSubscriberCount" }, "related_playlists": { "type": [ "string", "null" ], "description": "Leaf at author.ext.related_playlists" }, "topic_ids": { "type": [ "array", "null" ], "description": "Array at author.ext.topic_ids", "items": { "type": "string", "description": "String at author.ext.topic_ids" } }, "unsubscribed_trailer": { "type": [ "string", "null" ], "description": "String at author.ext.unsubscribed_trailer" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at author.ext.localizations" }, "monthly_listeners": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.monthly_listeners" }, "total_ratings": { "type": [ "integer", "null" ], "description": "Spotify podcasts only: how many listeners have rated the show. Cumulative over the show's whole run, so it reflects longevity as well as size, and it is NOT an audience count (Spotify publishes no play, download, subscriber or follower count for a podcast)" }, "average_rating": { "type": [ "integer", "null" ], "description": "Spotify podcasts only: mean listener rating from 0 to 5. Fractional (e.g. 4.66) despite the integer type this schema emits for every numeric leaf" }, "creator_username": { "type": [ "string", "null" ], "description": "String at author.ext.creator_username" }, "join_policy": { "type": [ "string", "null" ], "description": "String at author.ext.join_policy" }, "is_nsfw": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_nsfw" }, "rules": { "type": [ "array", "null" ], "description": "Array at author.ext.rules", "items": { "type": "string", "description": "Leaf at author.ext.rules" } }, "weekly_active_users": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.weekly_active_users" }, "weekly_contributions": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.weekly_contributions" }, "rules_text": { "type": [ "string", "null" ], "description": "String at author.ext.rules_text" }, "language": { "type": [ "string", "null" ], "description": "String at author.ext.language" }, "post_karma": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.post_karma" }, "comment_karma": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.comment_karma" }, "awardee_karma": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.awardee_karma" }, "trophy_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.trophy_count" }, "banner_url": { "type": [ "string", "null" ], "description": "String at author.ext.banner_url" }, "profile_title": { "type": [ "string", "null" ], "description": "String at author.ext.profile_title" }, "social_links": { "type": [ "array", "null" ], "description": "Array at author.ext.social_links", "items": { "type": "string", "description": "Leaf at author.ext.social_links" } }, "bio_link": { "type": [ "string", "null" ], "description": "String at author.ext.bio_link" }, "embed_html": { "type": [ "string", "null" ], "description": "String at author.ext.embed_html" }, "embed_url": { "type": [ "string", "null" ], "description": "String at author.ext.embed_url" }, "group": { "type": [ "string", "null" ], "description": "Leaf at author.ext.group" }, "search_hit": { "type": [ "object", "null" ], "description": "Nested object: author.ext.search_hit", "properties": { "match": { "type": [ "string", "null" ], "description": "Leaf at author.ext.search_hit.match" }, "title": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.title" }, "snippet": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.snippet" }, "evidence_url": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.evidence_url" }, "matched_urls": { "type": [ "array", "null" ], "description": "Array at author.ext.search_hit.matched_urls", "items": { "type": "string", "description": "String at author.ext.search_hit.matched_urls" } } } }, "blog_name": { "type": [ "string", "null" ], "description": "String at author.ext.blog_name" }, "blog_no": { "type": [ "string", "null" ], "description": "String at author.ext.blog_no" }, "visitors_today": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.visitors_today" }, "visitors_total": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.visitors_total" }, "topic": { "type": [ "string", "null" ], "description": "String at author.ext.topic" }, "power_blog": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.power_blog" }, "official_blog": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.official_blog" } } }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } } }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/profile", "data": { "author": { "id": "5831967", "username": "charlidamelio", "display_name": "charli d’amelio", "avatar_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.webp?dr=10399&refresh_token=e182b85d&x-expires=1791126000&x-signature=ql%2FeCVMHNzH0I76uiyVI961auNw%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=2472a6c6&idc=no1a", "bio": "orca enthusiast\nmeg thee stallion fan\ni post on youtube on saturdays (for the most part)", "verified": true, "followers": 160314015, "following": 1442, "posts_count": 3232, "likes_count": 12350281446, "url": "https://www.tiktok.com/@charlidamelio", "private": false, "joined_at": null, "ext": { "business_category": "Public Figure", "bio_link": "https://m.youtube.com/@CharlidAmelio" }, "location": "US" }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": null }, "_warnings": [ "computed.engagement_rate: author ratio exceeded 1.0 (raw: 77.038065); returned null. A lifetime likes/followers ratio is not a real engagement rate" ] }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T15:40:28.927Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/profile/videos": { "get": { "summary": "List TikTok user videos", "description": "Returns a paginated list of recent public videos posted by a TikTok user. Each video includes view count, like count, comment count, share count, caption, and thumbnail URL. `post.ext.region` is the ISO 3166-1 alpha-2 country TikTok registers that video to, normally the creator's account country when they posted. It is not the viewer's country, and a video with no registered country has it null. `post.ext.matched_song_id` is the catalogue song TikTok matched the row's sound to, present when it made a match: an official clip and the original sounds creators upload with it have different `post.ext.music_id` values and one `matched_song_id`, so group on it to count a song's uses (it is not a clipId for `/v1/tiktok/song/videos`). The creator's account country on its own is `author.location` from `/v1/tiktok/profile`. Profiles with TikTok 'audience controls' enabled (a login/age wall in the browser) are supported when looked up by `handle`; page-1 order on those gated accounts may follow recency rather than pinned-first.", "tags": [ "tiktok" ], "operationId": "get_tiktok_profile_videos", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 5, "x-credit-cost-formula": "1 credit per page. The default labels (sponsored, intent, niche) are free. label=mention, quality, ai_style, ai_written, injection, or label=intent with offer=, holds 4 extra credits and refunds down to 1 credit per started 25 posts that were newly judged: posts already labelled are free, a page where nothing could be judged refunds the whole extra, and a cached page is free. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total.", "x-socialcrawl-oneOf": [ [ "handle", "user_id" ] ], "parameters": [ { "name": "since", "in": "query", "required": false, "description": "Only videos published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Older videos are left off the page, and the page that reaches one ends the walk: `next_cursor` is not returned and `pagination.stopped_at` is `since`. Pinned videos sit out of date order and never end the walk. The page still costs what a page costs, so a daily poll pays for the pages it walks and no more.", "schema": { "type": "string" }, "example": "2026-09-01" }, { "name": "stop_at_id", "in": "query", "required": false, "description": "The id (`post.id`) or URL (`post.url`) of the newest video you already hold. The page stops just before it: that video and everything after it are left off, `next_cursor` is not returned, and `pagination.stopped_at` is `known_id`. A pinned video never counts as the stop point. If it is not on this page the page is returned in full with its cursor, so keep walking. `pagination.stopped_at` is `end` when the list ran out first and `null` while there is more to walk.", "schema": { "type": "string" } }, { "name": "handle", "in": "query", "required": false, "description": "TikTok username without the @ symbol (one of: handle, user_id; at least one required)", "schema": { "type": "string" }, "example": "charlidamelio" }, { "name": "user_id", "in": "query", "required": false, "description": "TikTok user id. Use this for faster responses. (one of: handle, user_id; at least one required)", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Accepted for compatibility and ignored on this endpoint: neither `latest` nor `popular` reorders the page. Videos come back in the source's own order, described above. To rank a creator's videos by views or likes, page through with `max_cursor` and sort the collected rows yourself.", "schema": { "type": "string", "enum": [ "latest", "popular" ] } }, { "name": "max_cursor", "in": "query", "required": false, "description": "Cursor to get more videos. Get 'max_cursor' from previous response. It is a Unix timestamp in milliseconds, and the page returns the videos posted before it, so you can also start from a date of your choice: `max_cursor=1590969600000` returns the videos posted just before 01/06/2020, then keep paging with each response's `max_cursor` (measured 22/10/2026: 27-31/05/2020 on khaby.lame, 26-31/12/2018 on nba). `until` only filters the rows of a page and does not move where the walk starts. Native upstream cursor param. Send the universal `cursor` instead: the API maps it to this name for you.", "deprecated": true, "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "description": "Region (Country) you want the proxy in. Defaults to US. It does not filter the videos. The country TikTok registers each video to is post.ext.region.", "schema": { "type": "string" } }, { "name": "trim", "in": "query", "required": false, "description": "Accepted for compatibility; the response is already the canonical shape, so this flag has no effect.", "schema": { "type": "boolean" } }, { "name": "format", "in": "query", "required": false, "description": "Optional. stationery files each video into wedding, birthday, birth, sympathy, seasonal greeting, or leaves it ungrouped. data.format_buckets gives the counts, the ungrouped share, and a by-day count when the page spans more than one day. A null save count stays null. brief= skips the walk when the page is not about that subject. No extra credits.", "schema": { "type": "string", "enum": [ "stationery" ] } }, { "name": "brief", "in": "query", "required": false, "description": "Optional, with format=stationery. The subject these videos should be about. When the page is not about it, data.format_buckets.skip_creator is true and the videos are not filed.", "schema": { "type": "string" } }, { "name": "label", "in": "query", "required": false, "description": "Optional CSV of SocialCrawl labels to add to every post. Without this param every page already carries sponsored, intent and niche, free; label= adds the labels you name to them (the defaults keep running). sponsored, intent and niche are free when asked for too; mention, quality, ai_style, intent with offer=, and injection add 1 credit per started 25 newly judged posts. judgments=off (or label=none) turns the default labels off. sponsored: is the post a paid or gifted promotion (p, 0 to 1), did it carry a disclosure marker such as #ad or 광고 (disclosed), is it likely paid with no marker (undisclosed), and which of the accounts it mentions does it promote (brand, or null). These are signals to review, never a finding. mention (needs brand=): is the post about that brand rather than something that shares its name (about_brand, 0 to 1), how it feels about the brand on five levels (sentiment_level 0 to 4 and sentiment_score 0 to 1, null when the post is not about the brand), is it sarcastic, which aspect it talks about (taste_or_quality, price_or_value, availability_or_delivery, health_or_safety, advertising_or_campaign, customer_service, none), and did the author buy or use it (first_hand). intent: what the author is mainly doing (label: asking_for_recommendation, comparing_options, switching_away, complaining, promoting, news_or_discussion, other, or null when unsure, with confidence), whether they read as a potential buyer rather than a seller (buyer, seller), how pressing the need is (urgency, 0 to 3), and, when you pass offer=, whether your offer would plausibly help them (fits_offer). niche: which of the 33 niches of the published taxonomy sc-niche-v1 the caption belongs to, or personal_no_niche, or other (label, confidence, taxonomy), with label null when the caption is too thin to tell or the pick is unsure. It reads the caption only, not the video. quality: how much checkable detail the caption carries (fact_density 0 to 3), whether it mainly asks for likes, replies, shares, follows or tags (engagement_bait, 0 to 1), whether it is written to provoke anger as a way to get engagement (rage_bait, 0 to 1; about the writing, never the side taken), whether it only repeats someone else's news or view (secondhand, 0 to 1), and what the post is mainly doing (post_aim: inform, opinion, sell, entertain, provoke, other). exclude=engagement_bait drops posts whose engagement_bait is 0.8 or higher. ai_style: writing patterns common in AI-generated text, judged on the text alone. It does not say who wrote the post, and a person who writes in this style is flagged too. Six patterns are judged, each a probability (0 to 1): binary_contrast (\"This is not X. It's Y.\"), faux_insight (\"Here's what nobody tells you\" and throat-clearing openers), colon_reveal (\"The best part: it learns.\"), profound_kicker (ends on an aphorism or mic-drop line), puffery (\"marks a pivotal moment\", \"highlighting the importance of\") and rhetorical_setup (\"What if I told you\", a question the post answers itself, \"Not a X. Not a Y. A Z.\"). Four are counted in the text: slop_words (words and phrases such as delve, leverage, robust, game changer, at the end of the day), em_dashes, emoji_bullets (lines that start with an emoji or a symbol bullet) and one_line_paragraphs (paragraphs that are one short line). pattern_count is how many patterns are present (a judged pattern at 0.8 or higher, slop_words 1 or more, em_dashes 2 or more, emoji_bullets 2 or more, one_line_paragraphs 5 or more) and markers lists their names, comma-separated. A post with less than about eight words of text is only counted, with every judged pattern 0. The judged patterns read the first 400 and the last 150 characters of a long post, and the counts read the whole post. exclude=ai_style drops posts with 2 or more patterns. ai_written: how likely the post was written by an AI model, from SocialCrawl's own text classifier, reading the opening of the post (about 1,000 characters): p (0 to 1, calibrated), level (likely (p 0.95 or higher), possible (p 0.71 or higher) or unlikely) and model (the model name; a new name means a new scale). A post under 8 words is too short to read: p null, level too_short. It is a probability, not proof: a person can be flagged and an AI-written post can pass, and the shorter the post the less certain it is. exclude=ai_written drops likely posts. injection flags text that addresses an AI system and tries to direct it (flagged, p); it never drops or rewrites a row. A post that could not be judged carries labels: null. Posts already labelled for anyone are free, and so is a cached page. data.labels reports what was judged and billed.", "schema": { "type": "string" } }, { "name": "exclude", "in": "query", "required": false, "description": "Optional CSV (engagement_bait, ai_style, ai_written). engagement_bait, only with label=quality, drops posts whose engagement_bait probability is 0.8 or higher. ai_style, only with label=ai_style, drops posts that show 2 or more of its writing patterns (pattern_count 2 or higher). ai_written, only with label=ai_written, drops posts whose level is likely (p 0.95 or higher), or whose p reaches your ai_written_threshold; a post too short to read is never dropped. Dropped posts are listed in data.labels.dropped_ids. A post that could not be judged is never dropped.", "schema": { "type": "string" } }, { "name": "ai_written_threshold", "in": "query", "required": false, "description": "Optional, only with label=ai_written and exclude=ai_written. The p (0 to 1) at which exclude=ai_written drops a post. Default 0.95 (level likely). 0.71 also drops possible posts: more AI posts go, and more posts by people with them.", "schema": { "type": "string" } }, { "name": "brand", "in": "query", "required": false, "description": "Required by label=mention, ignored otherwise. The brand or product the posts are judged against, up to 300 characters, for example brand=Buldak. Without it label=mention is skipped with the warning label_mention_needs_brand and is not billed.", "schema": { "type": "string" } }, { "name": "brand_description", "in": "query", "required": false, "description": "Optional, with label=mention. One plain sentence saying what the brand is, for example brand_description=Samyang's spicy instant noodle brand. Use it when the name is also an ordinary word or another company's name.", "schema": { "type": "string" } }, { "name": "offer", "in": "query", "required": false, "description": "Optional, with label=intent. One or two plain sentences saying what you sell, up to 300 characters, for example offer=A web design agency that builds websites for small businesses. Adds fits_offer to every post; without it fits_offer is null.", "schema": { "type": "string" } }, { "name": "judgments", "in": "query", "required": false, "description": "Optional, on (the default) or off. By default every row gains free SocialCrawl judgments (computed.labels, and computed.relevance on search endpoints), reported in data.labels (mode default) and data.relevance (origin default), each with a status (complete, partial or skipped) and pending: the rows still being judged when the page was sent, which carry null now and are filled on your next call or cached read. Default judgments never add credits, never change an existing field, and never drop or reorder a row. off returns the page exactly as before, with none of those keys. label=none does the same.", "schema": { "type": "string", "enum": [ "on", "off" ] } }, { "name": "dry_run", "in": "query", "required": false, "description": "Optional. When 1, return a cost preview for this labelled or relevance-filtered request without fetching the page or judging any row. data.estimate reports rows_expected, rows_cached, label_credits_min, label_credits_max and base_credits. 0 credits charged.", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "label_evidence", "in": "query", "required": false, "description": "Optional, only with label=. When 1, every labelled row also carries computed.labels_evidence. = { quote, sentence_index }: the sentence in the row that most clearly shows the label, copied verbatim. Absent or null when no single sentence shows it.", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "fit", "in": "query", "required": false, "description": "Optional. When goal, keep the rows and fields needed for the goal you pass in goal= (plus any that are uncertain, and the first and last), and replace the rest with a stub. data.held_back lists the held ids and a recall id that re-reads the full page from cache at no extra charge. Without this param the page is unchanged.", "schema": { "type": "string", "enum": [ "goal" ] } }, { "name": "goal", "in": "query", "required": false, "description": "Required by fit=goal. What you are trying to do, in your own words, up to 300 characters.", "schema": { "type": "string" } }, { "name": "fit_tokens", "in": "query", "required": false, "description": "Optional, only with fit=goal. Soft cap on how much of the page to keep, in tokens. Uncertain blocks and the first and last block are kept even if they exceed it.", "schema": { "type": "integer" } }, { "name": "until", "in": "query", "required": false, "description": "Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.", "schema": { "type": "string" } }, { "name": "max_pages", "in": "query", "required": false, "description": "1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "max_items", "in": "query", "required": false, "description": "1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: \"max_items\"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`\"time_budget\"`): send the returned cursor with the same params to continue.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "max_credits", "in": "query", "required": false, "description": "1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: \"max_credits\"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "cursor", "in": "query", "required": false, "description": "Universal pagination cursor. Send `pagination.next_cursor` from the previous response back verbatim: the API maps it to this endpoint's native `max_cursor` (cursor style). You never construct, decode, or look up a cursor. Omit it for page 1.", "schema": { "type": "string" } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/profile/videos" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical post wrappers ({ post, computed })", "items": { "type": "object", "description": "Canonical post wrapper", "properties": { "post": { "type": "object", "description": "Canonical Post object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "integer", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "integer", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "integer", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "integer", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "integer", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "integer", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "string", "null" ], "description": "Leaf at computed.labels" }, "labels_evidence": { "type": [ "string", "null" ], "description": "Leaf at computed.labels_evidence" } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/profile/videos", "data": { "items": [ { "post": { "id": "7691446353976691982", "url": "https://www.tiktok.com/@charlidamelio/video/7691446353976691982", "content": { "text": "dc@Dani ", "media_urls": "https://v16m.tiktokcdn-us.com/e5563ad24529b7f1085bfbdcef2e9b9c/6abfb021/video/tos/useast5/tos-useast5-ve-0068c001-tx/oYwVIFDtGRO0UEneT9EIGLFAgQeAc6B1eqfjVi/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=910&ft=B7c_4V~3wUxl7K2gUtIvk84jWLpiqcf.QjKJ~l5hgG0P3-I&mime_type=video_mp4&rc=MzdlO2U5MzM4OjwzNjU7NEBpam9lO3c5cnlyZDMzZzczNEAyX14xNTIyNl8xNDRhY2JgYSNlcG8yMmRrL3JhLS1kMS9zcw%3D%3D&vvpl=1&l=202610020722279D4DC70C4670BB810FC8&btag=e000b0000", "thumbnail_url": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/oA9LEIjVeDAbgG28VwF6OGqAGReAVFBeI1fW9E~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=8596&refresh_token=f3304388&x-expires=1791010800&x-signature=zrZgTI6WRht6xdCO0JnbBilHMWk%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=useast8&s=PUBLISH&sc=cover&biz_tag=tt_video", "duration_seconds": 14.558 }, "author": { "username": "charlidamelio", "display_name": "charli d’amelio", "avatar_url": "https://example.com/redacted", "verified": true }, "engagement": { "views": 1094895, "likes": 123934, "comments": 1028, "shares": 920, "saves": 4022 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2026-09-30T21:40:16.000Z", "ext": { "music_id": "7683532796899478294", "author_id": "user_3182ec", "author_followers": 160315286, "download_count": 452, "published_at_epoch": 1790804416 } }, "computed": { "engagement_rate": 0.114972, "language": null, "content_category": null, "estimated_reach": 1313874, "vs_creator": { "ratio": null, "metric": "views", "reason": "too_young" }, "labels": { "sponsored": { "p": 0.06, "disclosed": false, "undisclosed": false, "brand": null }, "intent": { "label": "other", "confidence": 0.86, "buyer": false, "seller": 0.24, "fits_offer": null, "urgency": 0.13 }, "niche": { "label": null, "confidence": null, "taxonomy": "sc-niche-v1" } } } }, { "post": { "id": "7691427157293239565", "url": "https://www.tiktok.com/@charlidamelio/video/7691427157293239565", "content": { "text": null, "media_urls": "https://v16m.tiktokcdn-us.com/99a5e0e2878d1f9848385ca5798667ec/6abfb019/video/tos/useast5/tos-useast5-pve-0068-tx/oEdE04TMQAzRIWeFZ6yDfO0GemAFgStADeAqI2/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=1932&ft=B7c_4V~3wUxl7K2gUtIvk84jWLpiqcf.QjKJ~l5hgG0P3-I&mime_type=video_mp4&rc=aGQ5NTVkZTY5ODw0NDg1NkBpM2Y7OXM5cjxwZDMzZzczNEAvNGEvMzVgXjUxYmJfMzVgYSNxZ29kMmRrc3JhLS1kMS9zcw%3D%3D&vvpl=1&l=202610020722279D4DC70C4670BB810FC8&btag=e000b0000", "thumbnail_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/oAEAaI45pbBv19gURHBmBEa6cE9JugaiFsirv~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=8596&refresh_token=f7eddc6a&x-expires=1791010800&x-signature=UmEq6VgYZWW098OAwIy57Bm0J1Q%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=useast8&biz_tag=tt_video&s=PUBLISH&sc=cover", "duration_seconds": 6.967 }, "author": { "username": "charlidamelio", "display_name": "charli d’amelio", "avatar_url": "https://example.com/redacted", "verified": true }, "engagement": { "views": 3599647, "likes": 635323, "comments": 1222, "shares": 14502, "saves": 14970 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2026-09-30T20:26:01.000Z", "ext": { "music_id": "7684150368565250075", "author_id": "user_3182ec", "author_followers": 160315286, "download_count": 1260, "published_at_epoch": 1790799961, "on_screen_texts": [ "hehehehhehehe" ] } }, "computed": { "engagement_rate": 0.180864, "language": null, "content_category": null, "estimated_reach": 4319576, "vs_creator": { "ratio": null, "metric": "views", "reason": "too_young" }, "labels": null } } ], "next_cursor": "sc2.eyJzIjoiaCIsImMiOiIxNzkwMjY2NDczOTMxIn0", "total": null, "creator_baseline": { "baseline": null, "reason": "fewer_than_eight", "rows_used": 7, "cadence": "measured" }, "labels": { "presets": [ "sponsored", "intent" ], "rows": 10, "labelled": 7, "cached": 7, "skipped": 3, "unjudged": 0, "dropped": 0, "dropped_ids": [], "extra_credits": 0, "methodology_version": "labels/1", "mode": "default", "status": "complete", "pending": 0, "pending_ids": [] }, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pYUNJc0ltTWlPaUl4Tnprd01qWTJORGN6T1RNeEluMCIsImUiOiJ0aWt0b2svcHJvZmlsZS92aWRlb3MiLCJwIjoibWF4X2N1cnNvciJ9", "has_more": true, "page_size": 10, "stopped_at": null }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T07:22:28.044Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/post": { "get": { "summary": "Get TikTok post details", "description": "Returns detailed information about a specific TikTok video including view count, like count, comment count, share count, caption, music info, author details, and video metadata. When the creator added on-screen text with TikTok's built-in text tool, the overlay text is returned in `data.post.ext.on_screen_texts` (absent when the video has none: text burned in with an external editor is not detectable from post data).", "tags": [ "tiktok" ], "operationId": "get_tiktok_post", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full URL of the TikTok video", "schema": { "type": "string" }, "example": "https://www.tiktok.com/@stoolpresidente/video/7623818255903329566" }, { "name": "region", "in": "query", "required": false, "description": "Two-letter country code for the proxy region (US, GB, FR, PH). The primary source does not take a region, so it is honoured only when a fallback source serves the request; a region-locked video (commonly from the Philippines) that fails on the primary is retried on the fallback with this value.", "schema": { "type": "string" } }, { "name": "trim", "in": "query", "required": false, "description": "Accepted for compatibility; the response is already the canonical shape, so this flag has no effect.", "schema": { "type": "boolean" } }, { "name": "download_media", "in": "query", "required": false, "description": "Set to true to also download the video/images and get back durable hosted media URLs under `data.post.ext.download_media_urls` (`[{ post_id, cdn_url, type, cached }]`). Use these for archiving; the raw `media_urls` are short-lived signed CDN links that expire. Adds a few seconds of latency while the media is fetched. Availability is source-dependent and most responses will not carry it: when the serving source cannot host durable copies the field is absent, the response carries a `data._warnings` note saying so, and `data.post.content.media_urls` still carries the media.", "schema": { "type": "boolean" } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/post" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } } }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached" ] }, "example": { "success": true, "platform": "youtube", "endpoint": "/v1/youtube/video", "data": { "post": { "id": "dQw4w9WgXcQ", "content": { "text": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)", "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg", "duration_seconds": 214, "media_urls": "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw" }, "author": { "username": "UCuAXFkgsw1L7xaCfnd5JJOw", "display_name": "Rick Astley", "avatar_url": null, "verified": null }, "engagement": { "views": 1789065639, "likes": 19216844, "comments": 2443809, "shares": null, "saves": null }, "published_at": "2009-10-25T06:57:33Z", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "ext": { "content_type": "video", "tags": [ "rick astley", "Never Gonna Give You Up", "nggyu", "never gonna give you up lyrics", "rick rolled", "Rick Roll", "rick astley official", "rickrolled", "Fortnite song", "Fortnite event", "Fortnite dance", "fortnite never gonna give you up", "rick roll", "rickrolling", "rick rolling", "never gonna give you up", "80s music", "rick astley new", "animated video", "rickroll", "meme songs", "never gonna give u up lyrics", "Rick Astley 2022", "never gonna let you down", "animated", "rick rolls 2022", "never gonna give you up karaoke" ], "categoryId": "10", "categoryTitle": "Music", "topicCategories": [ "https://en.wikipedia.org/wiki/Electronic_music", "https://en.wikipedia.org/wiki/Music", "https://en.wikipedia.org/wiki/Pop_music", "https://en.wikipedia.org/wiki/Rhythm_and_blues", "https://en.wikipedia.org/wiki/Soul_music" ], "duration": "PT3M34S", "license": "youtube", "madeForKids": false, "defaultAudioLanguage": "en", "hasPaidProductPlacement": false, "caption": "true", "description": "The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100. It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”. The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2. The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo", "default_language": "en" }, "flags": { "deleted": false, "nsfw": null, "spoiler": null, "pinned": null } }, "computed": { "engagement_rate": 0.012107, "language": "en", "content_category": "entertainment", "estimated_reach": 2146878767 } }, "credits_used": 1, "credits_remaining": 9999, "request_id": "req-8Kq2ZmR4vT9xLb3P", "cached": false, "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/post/comments": { "get": { "summary": "List TikTok post comments", "description": "Returns a list of comments on a specific TikTok video. Each comment includes the author username, comment text, like count, reply count, and creation timestamp.", "tags": [ "tiktok" ], "operationId": "get_tiktok_post_comments", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 7, "x-credit-cost-formula": "1 credit per page, with the default labels (sentiment, question, purchase_intent, complaint) included free. label=spam, toxic or low_quality holds 4 extra credits and refunds down to 1 credit per started 25 comments that were newly judged: comments already labelled are free, a page where nothing could be judged refunds the whole extra, and a cached page is free. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full URL of the TikTok video to fetch comments for", "schema": { "type": "string" }, "example": "https://www.tiktok.com/@stoolpresidente/video/7623818255903329566" }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor to get more comments. Get 'cursor' from previous response.", "schema": { "type": "string" } }, { "name": "trim", "in": "query", "required": false, "description": "Accepted for compatibility; the response is already the canonical shape, so this flag has no effect.", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "description": "Optional. Without it, comments come in TikTok's own order (a relevance ranking, not newest first). `recent` returns them newest first by published_at; `top` returns them by like count. TikTok has no newest-first order of its own, so `recent` sorts the comments that were read: set scan_pages to read more of the thread. data.scan.complete is true only when the whole thread was read.", "schema": { "type": "string", "enum": [ "top", "recent" ] } }, { "name": "scan_pages", "in": "query", "required": false, "description": "Optional, 1 to 3, default 1. Reads that many pages, drops comments repeated across pages, and returns them all in the `sort` order (TikTok's own order when sort is absent). Costs 1 credit for each page that added comments; a page of repeats is not billed. data.scan reports the pages read and billed and whether the thread ended.", "schema": { "type": "integer", "minimum": 1, "maximum": 3 } }, { "name": "label", "in": "query", "required": false, "description": "Optional CSV of SocialCrawl labels to add to every comment: sentiment, spam, question, purchase_intent, complaint, toxic, low_quality, injection. Without this param every page already carries sentiment, question, purchase_intent and complaint, free; label= adds the labels you name to them (the defaults keep running). Each comment gains computed.labels with probabilities (0 to 1), so you choose the cut-off; a comment that could not be judged carries labels: null. sentiment, question, purchase_intent and complaint are free when asked for too; spam, toxic, low_quality and injection add 1 credit per started 25 newly judged comments (comments already labelled for anyone are free, and so is a cached page). injection flags text that addresses an AI system and tries to direct it (flagged, p); it never drops or rewrites a row. judgments=off (or label=none) turns the default labels off. data.labels reports what was judged and billed.", "schema": { "type": "string" } }, { "name": "exclude", "in": "query", "required": false, "description": "Optional CSV (spam, low_quality), only with the same preset in label. Drops comments whose probability is 0.8 or higher and lists their ids in data.labels.dropped_ids. A comment that could not be judged is never dropped.", "schema": { "type": "string" } }, { "name": "judgments", "in": "query", "required": false, "description": "Optional, on (the default) or off. By default every row gains free SocialCrawl judgments (computed.labels, and computed.relevance on search endpoints), reported in data.labels (mode default) and data.relevance (origin default), each with a status (complete, partial or skipped) and pending: the rows still being judged when the page was sent, which carry null now and are filled on your next call or cached read. Default judgments never add credits, never change an existing field, and never drop or reorder a row. off returns the page exactly as before, with none of those keys. label=none does the same.", "schema": { "type": "string", "enum": [ "on", "off" ] } }, { "name": "dry_run", "in": "query", "required": false, "description": "Optional. When 1, return a cost preview for this labelled or relevance-filtered request without fetching the page or judging any row. data.estimate reports rows_expected, rows_cached, label_credits_min, label_credits_max and base_credits. 0 credits charged.", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "label_evidence", "in": "query", "required": false, "description": "Optional, only with label=. When 1, every labelled row also carries computed.labels_evidence. = { quote, sentence_index }: the sentence in the row that most clearly shows the label, copied verbatim. Absent or null when no single sentence shows it.", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "fit", "in": "query", "required": false, "description": "Optional. When goal, keep the rows and fields needed for the goal you pass in goal= (plus any that are uncertain, and the first and last), and replace the rest with a stub. data.held_back lists the held ids and a recall id that re-reads the full page from cache at no extra charge. Without this param the page is unchanged.", "schema": { "type": "string", "enum": [ "goal" ] } }, { "name": "goal", "in": "query", "required": false, "description": "Required by fit=goal. What you are trying to do, in your own words, up to 300 characters.", "schema": { "type": "string" } }, { "name": "fit_tokens", "in": "query", "required": false, "description": "Optional, only with fit=goal. Soft cap on how much of the page to keep, in tokens. Uncertain blocks and the first and last block are kept even if they exceed it.", "schema": { "type": "integer" } }, { "name": "since", "in": "query", "required": false, "description": "Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off the page, and the page that reaches one ends the walk: `next_cursor` is not returned and `pagination.stopped_at` is `since`. Sending it sets the newest-first sort shown in this endpoint's sort parameter (any other sort value is a free 400). The page still costs what a page costs, so you pay for the pages you walk and no more. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.", "schema": { "type": "string" } }, { "name": "max_pages", "in": "query", "required": false, "description": "1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "max_items", "in": "query", "required": false, "description": "1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: \"max_items\"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`\"time_budget\"`): send the returned cursor with the same params to continue.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "max_credits", "in": "query", "required": false, "description": "1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: \"max_credits\"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/post/comments" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical comment wrappers ({ comment })", "items": { "type": "object", "description": "Canonical comment wrapper", "properties": { "comment": { "type": "object", "description": "Canonical Comment object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific comment ID (always a string)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the comment on the source platform" }, "parent_id": { "type": [ "string", "null" ], "description": "Parent comment ID for nested replies, or null for top-level comments" }, "post_id": { "type": [ "string", "null" ], "description": "ID of the post this comment belongs to" }, "text": { "type": [ "string", "null" ], "description": "Comment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream: customers never see them." }, "author": { "type": "object", "description": "Subset of Author fields for the comment author", "properties": { "username": { "type": [ "string", "null" ], "description": "Comment author username (null when tombstoned)" }, "display_name": { "type": [ "string", "null" ], "description": "Comment author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to comment author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the comment author is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts on the comment", "properties": { "likes": { "type": [ "integer", "null" ], "description": "Like / upvote count" }, "replies": { "type": [ "integer", "null" ], "description": "Reply / child-comment count. `0` when the upstream structurally reports the count and the comment has no replies; `null` only when the upstream does not surface a reply count at all." } } }, "flags": { "type": "object", "description": "Boolean flags on the comment", "properties": { "pinned": { "type": [ "boolean", "null" ], "description": "Pinned flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the comment is tombstoned (always present, even when false)" }, "liked_by_creator": { "type": [ "boolean", "null" ], "description": "`/v1/instagram/post/comments` only: true when the post's creator liked (hearted) the comment, false when not, null when the source that served the call could not tell. Absent on every other endpoint." } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Comment creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `comment.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough tokens for reply expansion (present only on platforms that surface them)", "properties": { "replies_token": { "type": [ "string", "null" ], "description": "YouTube reply continuation token: pass to `/v1/youtube/video/comment/replies?continuationToken=`" }, "replies_cursor": { "type": [ "string", "null" ], "description": "Reddit reply-branch continuation cursor. Present when this comment's reply tree is truncated upstream: pass it back as `?cursor=` on `/v1/reddit/post/comments` to load the rest of the branch." }, "depth": { "type": [ "integer", "null" ], "description": "Reddit comment nesting depth as the source reports it: 0 on a top-level comment, 1 on a direct reply, and so on. Present when the thread arrived flat and was re-nested into `replies[]`, so you can verify that nesting independently." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string)." }, "feedback_id": { "type": [ "string", "null" ], "description": "Facebook comment feedback id: feeds `/v1/facebook/post/comment/replies`" }, "expansion_token": { "type": [ "string", "null" ], "description": "Facebook comment expansion/paginator token: feeds `/v1/facebook/post/comment/replies`" }, "author_id": { "type": [ "string", "null" ], "description": "The commenter's platform-native numeric user id, where the upstream exposes one." }, "ip_location": { "type": [ "string", "null" ], "description": "String at comment.ext.ip_location" }, "urn": { "type": [ "string", "null" ], "description": "String at comment.ext.urn" }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at comment.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at comment.ext.reaction_counts" } }, "is_edited": { "type": [ "boolean", "null" ], "description": "Boolean at comment.ext.is_edited" }, "previous_replies_token": { "type": [ "string", "null" ], "description": "String at comment.ext.previous_replies_token" }, "author_headline": { "type": [ "string", "null" ], "description": "String at comment.ext.author_headline" }, "updated_at": { "type": [ "string", "null" ], "description": "String at comment.ext.updated_at" }, "author_channel_id": { "type": [ "string", "null" ], "description": "String at comment.ext.author_channel_id" }, "author_url": { "type": [ "string", "null" ], "description": "String at comment.ext.author_url" }, "viewer_rating": { "type": [ "string", "null" ], "description": "String at comment.ext.viewer_rating" }, "text_original": { "type": [ "string", "null" ], "description": "String at comment.ext.text_original" }, "preview_replies": { "type": [ "array", "null" ], "description": "Array at comment.ext.preview_replies", "items": { "type": "string", "description": "Leaf at comment.ext.preview_replies" } }, "lookup": { "type": [ "string", "null" ], "description": "Leaf at comment.ext.lookup" }, "post_title": { "type": [ "string", "null" ], "description": "String at comment.ext.post_title" }, "post_url": { "type": [ "string", "null" ], "description": "String at comment.ext.post_url" }, "subreddit": { "type": [ "string", "null" ], "description": "String at comment.ext.subreddit" }, "subreddit_subscribers": { "type": [ "integer", "null" ], "description": "Numeric at comment.ext.subreddit_subscribers" }, "post_score": { "type": [ "integer", "null" ], "description": "Numeric at comment.ext.post_score" }, "post_comment_count": { "type": [ "integer", "null" ], "description": "Numeric at comment.ext.post_comment_count" }, "post_author": { "type": [ "string", "null" ], "description": "String at comment.ext.post_author" }, "post_published_at": { "type": [ "string", "null" ], "description": "String at comment.ext.post_published_at" }, "post_flair": { "type": [ "string", "null" ], "description": "String at comment.ext.post_flair" }, "is_submitter": { "type": [ "boolean", "null" ], "description": "Boolean at comment.ext.is_submitter" }, "edited_at": { "type": [ "string", "null" ], "description": "String at comment.ext.edited_at" }, "controversiality": { "type": [ "integer", "null" ], "description": "Numeric at comment.ext.controversiality" }, "content_language": { "type": [ "string", "null" ], "description": "ISO 639-1 language tag for this comment, when the source reports one. X writes `zxx` / `und` for no linguistic content; those collapse to null." }, "author_followers": { "type": [ "integer", "null" ], "description": "The commenter's follower count as embedded in this row. Snapshot as of whenever the replies source saw the account, not a live figure. On X this is present on every `tweet/replies` row." }, "author_following": { "type": [ "integer", "null" ], "description": "The commenter's following count as embedded in this row. Same snapshot caveat as `author_followers`." }, "author_posts_count": { "type": [ "integer", "null" ], "description": "The commenter's post count as embedded in this row. Same snapshot caveat as `author_followers`." }, "author_location": { "type": [ "string", "null" ], "description": "String at comment.ext.author_location" }, "quote_count": { "type": [ "integer", "null" ], "description": "How many quote-posts this comment has, when the source reports it. On X a reply is a tweet, so this is the same figure `post.ext.quote_count` carries on tweet lanes." }, "views": { "type": [ "integer", "null" ], "description": "View count for this comment, when the source reports it. On X a reply is a tweet and the count is public on posts from ~2022 onward." }, "saves": { "type": [ "integer", "null" ], "description": "Bookmark / save count for this comment, when the source reports it. On X this is `legacy.bookmark_count`." } } }, "replies": { "type": [ "array", "null" ], "description": "Nested reply tree: array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`.", "items": { "type": "object", "description": "Nested reply tree: array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`." } } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/post/comments", "data": { "items": [ { "comment": { "id": "7623869779602457374", "url": null, "parent_id": null, "post_id": "7623818255903329566", "text": "Sample comment text (redacted).", "author": { "username": "user_d39d34", "display_name": "user_bea79b", "avatar_url": "https://example.com/avatars/user_8300fa.png", "verified": false }, "engagement": { "likes": 13659, "replies": 25 }, "flags": { "pinned": false, "deleted": false }, "published_at": "2026-04-01T19:08:53.000Z", "ext": { "published_at_epoch": 1775070533 } }, "computed": { "language": "en" } }, { "comment": { "id": "7623876579169272607", "url": null, "parent_id": null, "post_id": "7623818255903329566", "text": "Sample comment text (redacted).", "author": { "username": "user_ba3f08", "display_name": "user_574add", "avatar_url": "https://example.com/avatars/user_376a05.png", "verified": false }, "engagement": { "likes": 4229, "replies": 45 }, "flags": { "pinned": false, "deleted": false }, "published_at": "2026-04-01T19:35:29.000Z", "ext": { "published_at_epoch": 1775072129 } }, "computed": { "language": "en" } } ], "next_cursor": "20", "total": 2200, "dropped": 0 }, "credits_used": 1, "credits_remaining": 9995, "request_id": "req-a1b2c3d4e5f6", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiMjAiLCJwIjoiY3Vyc29yIn0", "has_more": true, "page_size": 20 } } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/video/comment/replies": { "get": { "summary": "List TikTok comment replies", "description": "Fetches replies to a specific TikTok comment by its ID. Returns an array of comment objects each with text, user info, and creation time. Paginate with the cursor from the previous response.", "tags": [ "tiktok" ], "operationId": "get_tiktok_video_comment_replies", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 5, "x-credit-cost-formula": "1 credit per page, with the default labels (sentiment, question, purchase_intent, complaint) included free. label=spam, toxic or low_quality holds 4 extra credits and refunds down to 1 credit per started 25 comments that were newly judged: comments already labelled are free, a page where nothing could be judged refunds the whole extra, and a cached page is free. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total.", "parameters": [ { "name": "comment_id", "in": "query", "required": true, "description": "TikTok comment ID. This is the cid from the comments endpoint.", "schema": { "type": "string" }, "example": "7623828115408274207" }, { "name": "url", "in": "query", "required": true, "description": "TikTok video URL. This is the url from the comments endpoint.", "schema": { "type": "string" }, "example": "https://www.tiktok.com/@stoolpresidente/video/7623818255903329566" }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor to get more replies. Get 'cursor' from previous response.", "schema": { "type": "integer" } }, { "name": "label", "in": "query", "required": false, "description": "Optional CSV of SocialCrawl labels to add to every comment: sentiment, spam, question, purchase_intent, complaint, toxic, low_quality, injection. Without this param every page already carries sentiment, question, purchase_intent and complaint, free; label= adds the labels you name to them (the defaults keep running). Each comment gains computed.labels with probabilities (0 to 1), so you choose the cut-off; a comment that could not be judged carries labels: null. sentiment, question, purchase_intent and complaint are free when asked for too; spam, toxic, low_quality and injection add 1 credit per started 25 newly judged comments (comments already labelled for anyone are free, and so is a cached page). injection flags text that addresses an AI system and tries to direct it (flagged, p); it never drops or rewrites a row. judgments=off (or label=none) turns the default labels off. data.labels reports what was judged and billed.", "schema": { "type": "string" } }, { "name": "exclude", "in": "query", "required": false, "description": "Optional CSV (spam, low_quality), only with the same preset in label. Drops comments whose probability is 0.8 or higher and lists their ids in data.labels.dropped_ids. A comment that could not be judged is never dropped.", "schema": { "type": "string" } }, { "name": "judgments", "in": "query", "required": false, "description": "Optional, on (the default) or off. By default every row gains free SocialCrawl judgments (computed.labels, and computed.relevance on search endpoints), reported in data.labels (mode default) and data.relevance (origin default), each with a status (complete, partial or skipped) and pending: the rows still being judged when the page was sent, which carry null now and are filled on your next call or cached read. Default judgments never add credits, never change an existing field, and never drop or reorder a row. off returns the page exactly as before, with none of those keys. label=none does the same.", "schema": { "type": "string", "enum": [ "on", "off" ] } }, { "name": "dry_run", "in": "query", "required": false, "description": "Optional. When 1, return a cost preview for this labelled or relevance-filtered request without fetching the page or judging any row. data.estimate reports rows_expected, rows_cached, label_credits_min, label_credits_max and base_credits. 0 credits charged.", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "label_evidence", "in": "query", "required": false, "description": "Optional, only with label=. When 1, every labelled row also carries computed.labels_evidence. = { quote, sentence_index }: the sentence in the row that most clearly shows the label, copied verbatim. Absent or null when no single sentence shows it.", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "fit", "in": "query", "required": false, "description": "Optional. When goal, keep the rows and fields needed for the goal you pass in goal= (plus any that are uncertain, and the first and last), and replace the rest with a stub. data.held_back lists the held ids and a recall id that re-reads the full page from cache at no extra charge. Without this param the page is unchanged.", "schema": { "type": "string", "enum": [ "goal" ] } }, { "name": "goal", "in": "query", "required": false, "description": "Required by fit=goal. What you are trying to do, in your own words, up to 300 characters.", "schema": { "type": "string" } }, { "name": "fit_tokens", "in": "query", "required": false, "description": "Optional, only with fit=goal. Soft cap on how much of the page to keep, in tokens. Uncertain blocks and the first and last block are kept even if they exceed it.", "schema": { "type": "integer" } }, { "name": "since", "in": "query", "required": false, "description": "Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.", "schema": { "type": "string" } }, { "name": "max_pages", "in": "query", "required": false, "description": "1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "max_items", "in": "query", "required": false, "description": "1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: \"max_items\"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`\"time_budget\"`): send the returned cursor with the same params to continue.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "max_credits", "in": "query", "required": false, "description": "1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: \"max_credits\"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/video/comment/replies" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical comment wrappers ({ comment })", "items": { "type": "object", "description": "Canonical comment wrapper", "properties": { "comment": { "type": "object", "description": "Canonical Comment object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific comment ID (always a string)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the comment on the source platform" }, "parent_id": { "type": [ "string", "null" ], "description": "Parent comment ID for nested replies, or null for top-level comments" }, "post_id": { "type": [ "string", "null" ], "description": "ID of the post this comment belongs to" }, "text": { "type": [ "string", "null" ], "description": "Comment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream: customers never see them." }, "author": { "type": "object", "description": "Subset of Author fields for the comment author", "properties": { "username": { "type": [ "string", "null" ], "description": "Comment author username (null when tombstoned)" }, "display_name": { "type": [ "string", "null" ], "description": "Comment author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to comment author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the comment author is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts on the comment", "properties": { "likes": { "type": [ "integer", "null" ], "description": "Like / upvote count" }, "replies": { "type": [ "integer", "null" ], "description": "Reply / child-comment count. `0` when the upstream structurally reports the count and the comment has no replies; `null` only when the upstream does not surface a reply count at all." } } }, "flags": { "type": "object", "description": "Boolean flags on the comment", "properties": { "pinned": { "type": [ "boolean", "null" ], "description": "Pinned flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the comment is tombstoned (always present, even when false)" }, "liked_by_creator": { "type": [ "boolean", "null" ], "description": "`/v1/instagram/post/comments` only: true when the post's creator liked (hearted) the comment, false when not, null when the source that served the call could not tell. Absent on every other endpoint." } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Comment creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `comment.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough tokens for reply expansion (present only on platforms that surface them)", "properties": { "replies_token": { "type": [ "string", "null" ], "description": "YouTube reply continuation token: pass to `/v1/youtube/video/comment/replies?continuationToken=`" }, "replies_cursor": { "type": [ "string", "null" ], "description": "Reddit reply-branch continuation cursor. Present when this comment's reply tree is truncated upstream: pass it back as `?cursor=` on `/v1/reddit/post/comments` to load the rest of the branch." }, "depth": { "type": [ "integer", "null" ], "description": "Reddit comment nesting depth as the source reports it: 0 on a top-level comment, 1 on a direct reply, and so on. Present when the thread arrived flat and was re-nested into `replies[]`, so you can verify that nesting independently." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string)." }, "feedback_id": { "type": [ "string", "null" ], "description": "Facebook comment feedback id: feeds `/v1/facebook/post/comment/replies`" }, "expansion_token": { "type": [ "string", "null" ], "description": "Facebook comment expansion/paginator token: feeds `/v1/facebook/post/comment/replies`" }, "author_id": { "type": [ "string", "null" ], "description": "The commenter's platform-native numeric user id, where the upstream exposes one." }, "ip_location": { "type": [ "string", "null" ], "description": "String at comment.ext.ip_location" }, "urn": { "type": [ "string", "null" ], "description": "String at comment.ext.urn" }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at comment.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at comment.ext.reaction_counts" } }, "is_edited": { "type": [ "boolean", "null" ], "description": "Boolean at comment.ext.is_edited" }, "previous_replies_token": { "type": [ "string", "null" ], "description": "String at comment.ext.previous_replies_token" }, "author_headline": { "type": [ "string", "null" ], "description": "String at comment.ext.author_headline" }, "updated_at": { "type": [ "string", "null" ], "description": "String at comment.ext.updated_at" }, "author_channel_id": { "type": [ "string", "null" ], "description": "String at comment.ext.author_channel_id" }, "author_url": { "type": [ "string", "null" ], "description": "String at comment.ext.author_url" }, "viewer_rating": { "type": [ "string", "null" ], "description": "String at comment.ext.viewer_rating" }, "text_original": { "type": [ "string", "null" ], "description": "String at comment.ext.text_original" }, "preview_replies": { "type": [ "array", "null" ], "description": "Array at comment.ext.preview_replies", "items": { "type": "string", "description": "Leaf at comment.ext.preview_replies" } }, "lookup": { "type": [ "string", "null" ], "description": "Leaf at comment.ext.lookup" }, "post_title": { "type": [ "string", "null" ], "description": "String at comment.ext.post_title" }, "post_url": { "type": [ "string", "null" ], "description": "String at comment.ext.post_url" }, "subreddit": { "type": [ "string", "null" ], "description": "String at comment.ext.subreddit" }, "subreddit_subscribers": { "type": [ "integer", "null" ], "description": "Numeric at comment.ext.subreddit_subscribers" }, "post_score": { "type": [ "integer", "null" ], "description": "Numeric at comment.ext.post_score" }, "post_comment_count": { "type": [ "integer", "null" ], "description": "Numeric at comment.ext.post_comment_count" }, "post_author": { "type": [ "string", "null" ], "description": "String at comment.ext.post_author" }, "post_published_at": { "type": [ "string", "null" ], "description": "String at comment.ext.post_published_at" }, "post_flair": { "type": [ "string", "null" ], "description": "String at comment.ext.post_flair" }, "is_submitter": { "type": [ "boolean", "null" ], "description": "Boolean at comment.ext.is_submitter" }, "edited_at": { "type": [ "string", "null" ], "description": "String at comment.ext.edited_at" }, "controversiality": { "type": [ "integer", "null" ], "description": "Numeric at comment.ext.controversiality" }, "content_language": { "type": [ "string", "null" ], "description": "ISO 639-1 language tag for this comment, when the source reports one. X writes `zxx` / `und` for no linguistic content; those collapse to null." }, "author_followers": { "type": [ "integer", "null" ], "description": "The commenter's follower count as embedded in this row. Snapshot as of whenever the replies source saw the account, not a live figure. On X this is present on every `tweet/replies` row." }, "author_following": { "type": [ "integer", "null" ], "description": "The commenter's following count as embedded in this row. Same snapshot caveat as `author_followers`." }, "author_posts_count": { "type": [ "integer", "null" ], "description": "The commenter's post count as embedded in this row. Same snapshot caveat as `author_followers`." }, "author_location": { "type": [ "string", "null" ], "description": "String at comment.ext.author_location" }, "quote_count": { "type": [ "integer", "null" ], "description": "How many quote-posts this comment has, when the source reports it. On X a reply is a tweet, so this is the same figure `post.ext.quote_count` carries on tweet lanes." }, "views": { "type": [ "integer", "null" ], "description": "View count for this comment, when the source reports it. On X a reply is a tweet and the count is public on posts from ~2022 onward." }, "saves": { "type": [ "integer", "null" ], "description": "Bookmark / save count for this comment, when the source reports it. On X this is `legacy.bookmark_count`." } } }, "replies": { "type": [ "array", "null" ], "description": "Nested reply tree: array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`.", "items": { "type": "object", "description": "Nested reply tree: array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`." } } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/video/comment/replies", "data": { "items": [ { "comment": { "id": "7623849601356251917", "url": null, "parent_id": "7623828115408274207", "post_id": "7623818255903329566", "text": "Sample comment text (redacted).", "author": { "username": "user_96bf00", "display_name": "user_96bf00", "avatar_url": "https://example.com/avatars/user_77df50.png", "verified": false }, "engagement": { "likes": 258, "replies": null }, "flags": { "pinned": null, "deleted": false }, "published_at": "2026-04-01T17:50:55.000Z", "ext": { "published_at_epoch": 1775065855 } }, "computed": { "language": "en" } }, { "comment": { "id": "7624839492000006943", "url": null, "parent_id": "7623828115408274207", "post_id": "7623818255903329566", "text": "Sample comment text (redacted).", "author": { "username": "user_2658c7", "display_name": "user_14a5ff", "avatar_url": "https://example.com/avatars/user_56be8c.png", "verified": false }, "engagement": { "likes": 1, "replies": null }, "flags": { "pinned": null, "deleted": false }, "published_at": "2026-04-04T09:53:22.000Z", "ext": { "published_at_epoch": 1775296402 } }, "computed": { "language": null } } ], "next_cursor": "3", "total": 59, "dropped": 0 }, "credits_used": 1, "credits_remaining": 9995, "request_id": "req-a1b2c3d4e5f6", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiMyIsInAiOiJjdXJzb3IifQ", "has_more": true, "page_size": 3 } } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/comment": { "get": { "summary": "Look up one TikTok comment by URL or id", "description": "Resolves a single TikTok comment to a live comment object (current like count, reply count, pinned flag, author, timestamp) without you paginating the comment section. Pass `comment_url` (a `.../@{handle}/video/{id}?comment_id={cid}` link, an `m.tiktok.com` share link, or a `vm.tiktok.com`/`.../t/` shortlink: resolved automatically) OR `post_url` + `comment_id`. For a reply, also pass `parent_comment_id` (a reply URL does not carry its parent). Instead of a comment id you can search the comment section: `author_username` (find a specific author's comments) or `text_contains` (exact snippet) return up to `max` matches under `data.matches` (a search that matches nothing returns 404 and is fully refunded). The response includes a `lookup.position_hint`: pass it back on a later lookup of the same comment to make the re-check faster (the price is the same). Flat 2 credits (6 with `deep_scan=true`, which widens the scan budget); a not-found returns 404 and is fully refunded.", "tags": [ "tiktok" ], "operationId": "get_tiktok_comment", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 2, "x-credit-cost-min": 2, "x-credit-cost-max": 6, "x-credit-cost-formula": "2 credits for a standard lookup, 6 with `deep_scan=true`, which keeps paging the thread when the comment is not in the first pages. Reach for deep_scan only after a standard lookup comes back not-found", "x-socialcrawl-oneOf": [ [ "comment_url", "post_url" ] ], "parameters": [ { "name": "comment_url", "in": "query", "required": false, "description": "A TikTok comment URL: `https://www.tiktok.com/@{handle}/video/{videoId}?comment_id={cid}`, the `m.tiktok.com/v/{id}.html?...&share_comment_id={cid}` share form, or a `vm.tiktok.com/{code}` / `tiktok.com/t/{code}` shortlink. The `cid`/`comment_id`/`share_comment_id` query value may be numeric or the base64 form TikTok's share sheet emits (`?cid=NzY1...`): both are accepted; base64 is decoded automatically. Mutually exclusive with `post_url`+`comment_id`. (one of: comment_url, post_url; at least one required)", "schema": { "type": "string" }, "example": "https://www.tiktok.com/@mrbeast/video/7654638524729216287?comment_id=7654640784985211670" }, { "name": "post_url", "in": "query", "required": false, "description": "The post URL (`https://www.tiktok.com/@{handle}/video/{videoId}`). Combine with `comment_id`, or with `author_username`/`text_contains` for a search. (one of: comment_url, post_url; at least one required)", "schema": { "type": "string" } }, { "name": "comment_id", "in": "query", "required": false, "description": "The target comment's numeric id (the `cid` from the comments endpoint). Requires `post_url`. Note that TikTok share links carry a base64-encoded `cid`: pass such a link as `comment_url` instead (decoded automatically), or base64-decode the value to its digits before passing it here.", "schema": { "type": "string" } }, { "name": "parent_comment_id", "in": "query", "required": false, "description": "The parent comment's numeric id: supply this when the target is a reply so it can be resolved directly via the native replies endpoint.", "schema": { "type": "string" } }, { "name": "author_username", "in": "query", "required": false, "description": "Return up to `max` comments authored by this username (no comment id needed). Mutually exclusive with `text_contains` and any comment id.", "schema": { "type": "string" } }, { "name": "text_contains", "in": "query", "required": false, "description": "Return up to `max` comments whose text contains this snippet (case-insensitive). Mutually exclusive with `author_username` and any comment id.", "schema": { "type": "string" } }, { "name": "deep_scan", "in": "query", "required": false, "description": "Widen the scan budget for deeply-buried comments (raises the page ceiling and deadline). Bills 6 credits instead of 2.", "schema": { "type": "boolean" } }, { "name": "position_hint", "in": "query", "required": false, "description": "Opaque token from a prior lookup's `lookup.position_hint`. Passing it back probes the comment's last-known location first, making a re-check of an already-found comment cheap.", "schema": { "type": "string" } }, { "name": "max", "in": "query", "required": false, "description": "For `author_username`/`text_contains` search: max matches to return (1-20, default 5).", "schema": { "type": "integer" } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/comment" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "id": { "type": "string", "description": "Platform-specific comment ID (always a string)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the comment on the source platform" }, "parent_id": { "type": [ "string", "null" ], "description": "Parent comment ID for nested replies, or null for top-level comments" }, "post_id": { "type": [ "string", "null" ], "description": "ID of the post this comment belongs to" }, "text": { "type": [ "string", "null" ], "description": "Comment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream: customers never see them." }, "author": { "type": "object", "description": "Subset of Author fields for the comment author", "properties": { "username": { "type": [ "string", "null" ], "description": "Comment author username (null when tombstoned)" }, "display_name": { "type": [ "string", "null" ], "description": "Comment author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to comment author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the comment author is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts on the comment", "properties": { "likes": { "type": [ "integer", "null" ], "description": "Like / upvote count" }, "replies": { "type": [ "integer", "null" ], "description": "Reply / child-comment count. `0` when the upstream structurally reports the count and the comment has no replies; `null` only when the upstream does not surface a reply count at all." } } }, "flags": { "type": "object", "description": "Boolean flags on the comment", "properties": { "pinned": { "type": [ "boolean", "null" ], "description": "Pinned flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the comment is tombstoned (always present, even when false)" }, "liked_by_creator": { "type": [ "boolean", "null" ], "description": "`/v1/instagram/post/comments` only: true when the post's creator liked (hearted) the comment, false when not, null when the source that served the call could not tell. Absent on every other endpoint." } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Comment creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `comment.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough tokens for reply expansion (present only on platforms that surface them)", "properties": { "replies_token": { "type": [ "string", "null" ], "description": "YouTube reply continuation token: pass to `/v1/youtube/video/comment/replies?continuationToken=`" }, "replies_cursor": { "type": [ "string", "null" ], "description": "Reddit reply-branch continuation cursor. Present when this comment's reply tree is truncated upstream: pass it back as `?cursor=` on `/v1/reddit/post/comments` to load the rest of the branch." }, "depth": { "type": [ "integer", "null" ], "description": "Reddit comment nesting depth as the source reports it: 0 on a top-level comment, 1 on a direct reply, and so on. Present when the thread arrived flat and was re-nested into `replies[]`, so you can verify that nesting independently." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string)." }, "feedback_id": { "type": [ "string", "null" ], "description": "Facebook comment feedback id: feeds `/v1/facebook/post/comment/replies`" }, "expansion_token": { "type": [ "string", "null" ], "description": "Facebook comment expansion/paginator token: feeds `/v1/facebook/post/comment/replies`" }, "author_id": { "type": [ "string", "null" ], "description": "The commenter's platform-native numeric user id, where the upstream exposes one." }, "ip_location": { "type": [ "string", "null" ], "description": "String at comment.ext.ip_location" }, "urn": { "type": [ "string", "null" ], "description": "String at comment.ext.urn" }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at comment.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at comment.ext.reaction_counts" } }, "is_edited": { "type": [ "boolean", "null" ], "description": "Boolean at comment.ext.is_edited" }, "previous_replies_token": { "type": [ "string", "null" ], "description": "String at comment.ext.previous_replies_token" }, "author_headline": { "type": [ "string", "null" ], "description": "String at comment.ext.author_headline" }, "updated_at": { "type": [ "string", "null" ], "description": "String at comment.ext.updated_at" }, "author_channel_id": { "type": [ "string", "null" ], "description": "String at comment.ext.author_channel_id" }, "author_url": { "type": [ "string", "null" ], "description": "String at comment.ext.author_url" }, "viewer_rating": { "type": [ "string", "null" ], "description": "String at comment.ext.viewer_rating" }, "text_original": { "type": [ "string", "null" ], "description": "String at comment.ext.text_original" }, "preview_replies": { "type": [ "array", "null" ], "description": "Array at comment.ext.preview_replies", "items": { "type": "string", "description": "Leaf at comment.ext.preview_replies" } }, "lookup": { "type": [ "string", "null" ], "description": "Leaf at comment.ext.lookup" }, "post_title": { "type": [ "string", "null" ], "description": "String at comment.ext.post_title" }, "post_url": { "type": [ "string", "null" ], "description": "String at comment.ext.post_url" }, "subreddit": { "type": [ "string", "null" ], "description": "String at comment.ext.subreddit" }, "subreddit_subscribers": { "type": [ "integer", "null" ], "description": "Numeric at comment.ext.subreddit_subscribers" }, "post_score": { "type": [ "integer", "null" ], "description": "Numeric at comment.ext.post_score" }, "post_comment_count": { "type": [ "integer", "null" ], "description": "Numeric at comment.ext.post_comment_count" }, "post_author": { "type": [ "string", "null" ], "description": "String at comment.ext.post_author" }, "post_published_at": { "type": [ "string", "null" ], "description": "String at comment.ext.post_published_at" }, "post_flair": { "type": [ "string", "null" ], "description": "String at comment.ext.post_flair" }, "is_submitter": { "type": [ "boolean", "null" ], "description": "Boolean at comment.ext.is_submitter" }, "edited_at": { "type": [ "string", "null" ], "description": "String at comment.ext.edited_at" }, "controversiality": { "type": [ "integer", "null" ], "description": "Numeric at comment.ext.controversiality" }, "content_language": { "type": [ "string", "null" ], "description": "ISO 639-1 language tag for this comment, when the source reports one. X writes `zxx` / `und` for no linguistic content; those collapse to null." }, "author_followers": { "type": [ "integer", "null" ], "description": "The commenter's follower count as embedded in this row. Snapshot as of whenever the replies source saw the account, not a live figure. On X this is present on every `tweet/replies` row." }, "author_following": { "type": [ "integer", "null" ], "description": "The commenter's following count as embedded in this row. Same snapshot caveat as `author_followers`." }, "author_posts_count": { "type": [ "integer", "null" ], "description": "The commenter's post count as embedded in this row. Same snapshot caveat as `author_followers`." }, "author_location": { "type": [ "string", "null" ], "description": "String at comment.ext.author_location" }, "quote_count": { "type": [ "integer", "null" ], "description": "How many quote-posts this comment has, when the source reports it. On X a reply is a tweet, so this is the same figure `post.ext.quote_count` carries on tweet lanes." }, "views": { "type": [ "integer", "null" ], "description": "View count for this comment, when the source reports it. On X a reply is a tweet and the count is public on posts from ~2022 onward." }, "saves": { "type": [ "integer", "null" ], "description": "Bookmark / save count for this comment, when the source reports it. On X this is `legacy.bookmark_count`." } } }, "replies": { "type": [ "array", "null" ], "description": "Nested reply tree: array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`.", "items": { "type": "object", "description": "Nested reply tree: array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`." } }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } } }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/comment", "data": { "comment": { "id": "7654640784985211670", "url": "https://example.com/redacted", "parent_id": null, "post_id": "7654638524729216287", "text": "Sample comment text (redacted).", "author": { "username": "user_e55366", "display_name": "user_6ca290", "avatar_url": "https://example.com/avatars/user_0043be.png", "verified": false }, "engagement": { "likes": 20370, "replies": 49 }, "flags": { "pinned": false, "deleted": false }, "published_at": "2026-06-23T17:15:54.000Z", "ext": { "published_at_epoch": 1782234954 } }, "computed": { "language": "en" }, "lookup": { "found_via": "id_scan", "pages_fetched": 5, "comments_scanned": 100, "sort_basis": "top", "position_hint": "eyJ2IjoxLCJwbGF0Zm9ybSI6InRpa3RvayIsImN1cnNvciI6MH0" } }, "credits_used": 2, "credits_remaining": 9999, "request_id": "req-8Kq2ZmR4vT9xLb3P", "cached": false, "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/search": { "get": { "summary": "Search TikTok videos by keyword", "description": "Searches TikTok for videos matching a keyword query. Returns a list of matching videos with view counts, like counts, captions, author info, and thumbnails. TikTok itself ends one query's results at about 200 to 400 videos; send `expand=true` to keep paging through TikTok's related searches for the query and its other rankings (1,244 distinct videos for `coffee` on 26/10/2026, against 292 for the query alone). Each page aims at 25 or more videos the walk has not returned: when `since`/`until` or the walk's de-duplication removes rows, the page reads further on before it is served, at no extra credits. A shorter page is normal near the end of TikTok's results.For one hashtag's own feed, use /v1/tiktok/search/hashtag. Every row carries post.ext.region, the ISO 3166-1 alpha-2 country TikTok registered the video to (normally the creator's account country when they posted). The region= request parameter only sets the proxy; it does not filter. Keep one country by filtering on post.ext.region. Every row also carries the creator on it: post.author.username, post.ext.author_id (the creator's numeric user id) and post.ext.author_followers, the creator's follower count as the search source reported it, so a page filtered on post.ext.region is already a creator list for that country. For the creator's current exact follower count, bio and links, pass the username or id to /v1/tiktok/profile (?handle= or ?user_id=) at 1 credit, or batch up to 50 usernames per call through POST /v1/prism/profiles at 1 credit per resolved profile. Deduplicate creators across the whole crawl first; the same creators recur across keywords. `post.ext.matched_song_id` is the catalogue song TikTok matched the row's sound to, present when it made a match: an official clip and the original sounds creators upload with it have different `post.ext.music_id` values and one `matched_song_id`, so group on it to count a song's uses (it is not a clipId for `/v1/tiktok/song/videos`).", "tags": [ "tiktok" ], "operationId": "get_tiktok_search", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 42, "x-credit-cost-formula": "1 credit for the page, including any limit of 30 or less. A limit above 30 holds ceil(N/4)+2 credits for the N rows the source fills (60 to 120, rounded up to a multiple of 30), 17 at 60 and 32 at 120, and unfilled slots are refunded. Repeated videos are removed after billing. Relevance against your query (by default, or with relevance=) is free. Adding relevant_to= holds 5 extra credits and refunds down to 1 credit per started 25 rows that were newly judged: rows already judged for the same topic are free, a page where nothing could be judged refunds the whole extra, and a cached page is free. The default labels (sponsored, intent, niche) are free. label=mention, quality, ai_style, ai_written, injection, or label=intent with offer=, holds 5 extra credits and refunds down to 1 credit per started 25 posts that were newly judged: posts already labelled are free, a page where nothing could be judged refunds the whole extra, and a cached page is free. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total. With `seen`, a page's price falls with its share of rows you already received under that id; credits for joined data (`include=`) are never discounted.", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search keyword or phrase to find TikTok videos", "schema": { "type": "string" }, "example": "cooking recipes" }, { "name": "date_posted", "in": "query", "required": false, "description": "Time Frame", "schema": { "type": "string", "enum": [ "yesterday", "this-week", "this-month", "last-3-months", "last-6-months", "all-time" ] } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort by", "schema": { "type": "string", "enum": [ "relevance", "most-liked", "date-posted" ] } }, { "name": "region", "in": "query", "required": false, "description": "Sets the proxy country (ISO 3166-1 alpha-2). It does not filter the page to that country. Each row already carries post.ext.region, the country the video is registered to; filter on that leaf when you need only one country.", "schema": { "type": "string" }, "example": "ES" }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor to get more videos. Get 'cursor' from previous response. Ignored when `limit` is above 30: that call is a single page.", "schema": { "type": "integer" } }, { "name": "trim", "in": "query", "required": false, "description": "Accepted for compatibility; the response is already the canonical shape, so this flag has no effect.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "A limit of 30 or less returns the first limit rows of the normal page for 1 credit; next_cursor still steps the whole page of about 30, so the rest of that page is skipped. A limit above 30 selects the bulk labeled page: up to 120 videos in one call, each with post.ext.region. The value rounds up to the next multiple of 30 (60, 90 or 120). 17 credits at 60, 32 at 120; slots the source does not fill are refunded. date_posted and sort_by apply on the bulk page too. The source can repeat a video; repeats are removed, so a 120 page is often a little under 120 unique videos. Does not filter by country; drop rows yourself on post.ext.region.", "schema": { "type": "integer", "minimum": 1, "maximum": 120 }, "example": 120 }, { "name": "expand", "in": "query", "required": false, "description": "Send `true` to keep paging past TikTok's own limit for one query, which ends a walk at about 200 to 400 videos. When your ranking runs out, the walk continues with TikTok's related searches for your query that contain every word of it (for `coffee`: `iced coffee at home`, `coffee cold brew recipe`) and then with the other two rankings, each to its end, keeping your `date_posted` and `region`. A video can come up again on a later step, so deduplicate on `post.id`. Rows after your own ranking are not in your `sort_by` order. Every page is 1 credit, as usual; page with `cursor`, or collect many pages in one call with `max_items`.", "schema": { "type": "boolean" } }, { "name": "relevance", "in": "query", "required": false, "description": "Optional. Without this param every row already carries computed.relevance against your query, free ({ p, sense, depth, spam }: is this row about what your query means, or a different thing that shares its words?), and nothing is dropped or reordered. score asks for it explicitly and waits for every row; filter also drops the rows that are not about your query, and lists their ids in data.relevance.dropped_ids. Your query is the topic; nothing to configure. A row that could not be judged is never dropped and carries relevance: null. Pagination is unchanged, so a filtered page can hold fewer rows. Free with your query as the topic; with relevant_to it adds 1 credit per started 25 newly judged rows (rows already judged for the same topic are free, and so is a cached page).", "schema": { "type": "string", "enum": [ "score", "filter" ] } }, { "name": "relevance_threshold", "in": "query", "required": false, "description": "Optional, only with relevance. The probability (0 to 1) a row must reach to be kept by relevance=filter. Default 0.5. Lower keeps more rows, higher keeps fewer.", "schema": { "type": "string" } }, { "name": "relevant_to", "in": "query", "required": false, "description": "Optional, only with relevance. Up to 200 characters describing what you mean, used as the topic instead of the query. Use it when the query is ambiguous, for example query=cleopatra with relevant_to=Cleopatra, the IGT slot game.", "schema": { "type": "string" } }, { "name": "judgments", "in": "query", "required": false, "description": "Optional, on (the default) or off. By default every row gains free SocialCrawl judgments (computed.labels, and computed.relevance on search endpoints), reported in data.labels (mode default) and data.relevance (origin default), each with a status (complete, partial or skipped) and pending: the rows still being judged when the page was sent, which carry null now and are filled on your next call or cached read. Default judgments never add credits, never change an existing field, and never drop or reorder a row. off returns the page exactly as before, with none of those keys. label=none does the same.", "schema": { "type": "string", "enum": [ "on", "off" ] } }, { "name": "dry_run", "in": "query", "required": false, "description": "Optional. When 1, return a cost preview for this labelled or relevance-filtered request without fetching the page or judging any row. data.estimate reports rows_expected, rows_cached, label_credits_min, label_credits_max and base_credits. 0 credits charged.", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "fit", "in": "query", "required": false, "description": "Optional. When goal, keep the rows and fields needed for the goal you pass in goal= (plus any that are uncertain, and the first and last), and replace the rest with a stub. data.held_back lists the held ids and a recall id that re-reads the full page from cache at no extra charge. Without this param the page is unchanged.", "schema": { "type": "string", "enum": [ "goal" ] } }, { "name": "goal", "in": "query", "required": false, "description": "Required by fit=goal. What you are trying to do, in your own words, up to 300 characters.", "schema": { "type": "string" } }, { "name": "fit_tokens", "in": "query", "required": false, "description": "Optional, only with fit=goal. Soft cap on how much of the page to keep, in tokens. Uncertain blocks and the first and last block are kept even if they exceed it.", "schema": { "type": "integer" } }, { "name": "label", "in": "query", "required": false, "description": "Optional CSV of SocialCrawl labels to add to every post. Without this param every page already carries sponsored, intent and niche, free; label= adds the labels you name to them (the defaults keep running). sponsored, intent and niche are free when asked for too; mention, quality, ai_style, intent with offer=, and injection add 1 credit per started 25 newly judged posts. judgments=off (or label=none) turns the default labels off. sponsored: is the post a paid or gifted promotion (p, 0 to 1), did it carry a disclosure marker such as #ad or 광고 (disclosed), is it likely paid with no marker (undisclosed), and which of the accounts it mentions does it promote (brand, or null). These are signals to review, never a finding. mention (needs brand=): is the post about that brand rather than something that shares its name (about_brand, 0 to 1), how it feels about the brand on five levels (sentiment_level 0 to 4 and sentiment_score 0 to 1, null when the post is not about the brand), is it sarcastic, which aspect it talks about (taste_or_quality, price_or_value, availability_or_delivery, health_or_safety, advertising_or_campaign, customer_service, none), and did the author buy or use it (first_hand). intent: what the author is mainly doing (label: asking_for_recommendation, comparing_options, switching_away, complaining, promoting, news_or_discussion, other, or null when unsure, with confidence), whether they read as a potential buyer rather than a seller (buyer, seller), how pressing the need is (urgency, 0 to 3), and, when you pass offer=, whether your offer would plausibly help them (fits_offer). niche: which of the 33 niches of the published taxonomy sc-niche-v1 the caption belongs to, or personal_no_niche, or other (label, confidence, taxonomy), with label null when the caption is too thin to tell or the pick is unsure. It reads the caption only, not the video. quality: how much checkable detail the caption carries (fact_density 0 to 3), whether it mainly asks for likes, replies, shares, follows or tags (engagement_bait, 0 to 1), whether it is written to provoke anger as a way to get engagement (rage_bait, 0 to 1; about the writing, never the side taken), whether it only repeats someone else's news or view (secondhand, 0 to 1), and what the post is mainly doing (post_aim: inform, opinion, sell, entertain, provoke, other). exclude=engagement_bait drops posts whose engagement_bait is 0.8 or higher. ai_style: writing patterns common in AI-generated text, judged on the text alone. It does not say who wrote the post, and a person who writes in this style is flagged too. Six patterns are judged, each a probability (0 to 1): binary_contrast (\"This is not X. It's Y.\"), faux_insight (\"Here's what nobody tells you\" and throat-clearing openers), colon_reveal (\"The best part: it learns.\"), profound_kicker (ends on an aphorism or mic-drop line), puffery (\"marks a pivotal moment\", \"highlighting the importance of\") and rhetorical_setup (\"What if I told you\", a question the post answers itself, \"Not a X. Not a Y. A Z.\"). Four are counted in the text: slop_words (words and phrases such as delve, leverage, robust, game changer, at the end of the day), em_dashes, emoji_bullets (lines that start with an emoji or a symbol bullet) and one_line_paragraphs (paragraphs that are one short line). pattern_count is how many patterns are present (a judged pattern at 0.8 or higher, slop_words 1 or more, em_dashes 2 or more, emoji_bullets 2 or more, one_line_paragraphs 5 or more) and markers lists their names, comma-separated. A post with less than about eight words of text is only counted, with every judged pattern 0. The judged patterns read the first 400 and the last 150 characters of a long post, and the counts read the whole post. exclude=ai_style drops posts with 2 or more patterns. ai_written: how likely the post was written by an AI model, from SocialCrawl's own text classifier, reading the opening of the post (about 1,000 characters): p (0 to 1, calibrated), level (likely (p 0.95 or higher), possible (p 0.71 or higher) or unlikely) and model (the model name; a new name means a new scale). A post under 8 words is too short to read: p null, level too_short. It is a probability, not proof: a person can be flagged and an AI-written post can pass, and the shorter the post the less certain it is. exclude=ai_written drops likely posts. injection flags text that addresses an AI system and tries to direct it (flagged, p); it never drops or rewrites a row. A post that could not be judged carries labels: null. Posts already labelled for anyone are free, and so is a cached page. data.labels reports what was judged and billed.", "schema": { "type": "string" } }, { "name": "exclude", "in": "query", "required": false, "description": "Optional CSV (engagement_bait, ai_style, ai_written). engagement_bait, only with label=quality, drops posts whose engagement_bait probability is 0.8 or higher. ai_style, only with label=ai_style, drops posts that show 2 or more of its writing patterns (pattern_count 2 or higher). ai_written, only with label=ai_written, drops posts whose level is likely (p 0.95 or higher), or whose p reaches your ai_written_threshold; a post too short to read is never dropped. Dropped posts are listed in data.labels.dropped_ids. A post that could not be judged is never dropped.", "schema": { "type": "string" } }, { "name": "ai_written_threshold", "in": "query", "required": false, "description": "Optional, only with label=ai_written and exclude=ai_written. The p (0 to 1) at which exclude=ai_written drops a post. Default 0.95 (level likely). 0.71 also drops possible posts: more AI posts go, and more posts by people with them.", "schema": { "type": "string" } }, { "name": "brand", "in": "query", "required": false, "description": "Required by label=mention, ignored otherwise. The brand or product the posts are judged against, up to 300 characters, for example brand=Buldak. Without it label=mention is skipped with the warning label_mention_needs_brand and is not billed.", "schema": { "type": "string" } }, { "name": "brand_description", "in": "query", "required": false, "description": "Optional, with label=mention. One plain sentence saying what the brand is, for example brand_description=Samyang's spicy instant noodle brand. Use it when the name is also an ordinary word or another company's name.", "schema": { "type": "string" } }, { "name": "offer", "in": "query", "required": false, "description": "Optional, with label=intent. One or two plain sentences saying what you sell, up to 300 characters, for example offer=A web design agency that builds websites for small businesses. Adds fits_offer to every post; without it fits_offer is null.", "schema": { "type": "string" } }, { "name": "label_evidence", "in": "query", "required": false, "description": "Optional, only with label=. When 1, every labelled row also carries computed.labels_evidence. = { quote, sentence_index }: the sentence in the row that most clearly shows the label, copied verbatim. Absent or null when no single sentence shows it.", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "since", "in": "query", "required": false, "description": "Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.", "schema": { "type": "string" } }, { "name": "min_views", "in": "query", "required": false, "description": "Keep only rows with at least this many views (`post.engagement.views`). A row whose view count is unknown is discarded, so every returned row meets the floor. Filtering runs on our side after each page is fetched, so every page walked is billed as usual; `data.walk.discarded` counts what was removed and why. Each page is its own entry in `GET /v1/credits/transactions`, under the page's request id listed in `data.walk.request_ids`.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "max_age_days", "in": "query", "required": false, "description": "Keep only rows published within this many days (`post.published_at`), 1 to 3650. A row with no date is discarded. Filtering runs on our side after each page is fetched, so every page walked is billed as usual; `data.walk.discarded` counts what was removed and why. Each page is its own entry in `GET /v1/credits/transactions`, under the page's request id listed in `data.walk.request_ids`.", "schema": { "type": "integer", "minimum": 1, "maximum": 3650 } }, { "name": "country", "in": "query", "required": false, "description": "Comma-separated two-letter ISO 3166-1 codes, for example `US,GB`. Keep only videos TikTok registers to one of these countries (`post.ext.region`); a row with no country is discarded. This filters rows; it does not change where the search runs (that is `region`). Filtering runs on our side after each page is fetched, so every page walked is billed as usual; `data.walk.discarded` counts what was removed and why. Each page is its own entry in `GET /v1/credits/transactions`, under the page's request id listed in `data.walk.request_ids`.", "schema": { "type": "string" } }, { "name": "exclude_country", "in": "query", "required": false, "description": "Comma-separated two-letter ISO 3166-1 codes, for example `IN`. Discard videos TikTok registers to any of these countries (`post.ext.region`); a row with no country is kept. Filtering runs on our side after each page is fetched, so every page walked is billed as usual; `data.walk.discarded` counts what was removed and why. Each page is its own entry in `GET /v1/credits/transactions`, under the page's request id listed in `data.walk.request_ids`.", "schema": { "type": "string" } }, { "name": "sort_rows", "in": "query", "required": false, "description": "`views`: return the kept rows ordered by view count, highest first, across every page walked. Rows without a view count go last.", "schema": { "type": "string", "enum": [ "views" ] } }, { "name": "max_pages", "in": "query", "required": false, "description": "1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them (after any filter). Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "max_items", "in": "query", "required": false, "description": "1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows (after any filter), then stop with `data.walk.stopped: \"max_items\"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`\"time_budget\"`): send the returned cursor with the same params to continue.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "max_credits", "in": "query", "required": false, "description": "1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: \"max_credits\"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "seen", "in": "query", "required": false, "description": "An id you choose (1 to 64 letters, digits, `.`, `_` or `-`). Rows your account already received under the same `seen` id are removed from the page, and the page price falls with the share of repeats: page credits x new rows / rows on the page, rounded up, so a page of nothing but repeats is free. Only the page's own price is discounted: credits for joined data (`include=`) are charged only for rows you have not received, and are never discounted. The memory lasts 24 hours from the last call that used the id, holds row ids only, and is private to your account. Use one id across a set of related searches; `data.walk.repeats` counts what was removed.", "schema": { "type": "string" } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/search" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical post wrappers ({ post, computed })", "items": { "type": "object", "description": "Canonical post wrapper", "properties": { "post": { "type": "object", "description": "Canonical Post object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "integer", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "integer", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "integer", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "integer", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "integer", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "integer", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "string", "null" ], "description": "Leaf at computed.labels" }, "labels_evidence": { "type": [ "string", "null" ], "description": "Leaf at computed.labels_evidence" } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/search", "data": { "items": [ { "post": { "id": "7654273990533434657", "url": "https://www.tiktok.com/@user_83a4f7/video/7654273990533434657", "content": { "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "media_urls": "https://v45.tiktokcdn-eu.com/6b8d15482b3047bcd3125a7cda86d5b2/6ac0ad58/video/tos/useast2a/tos-useast2a-ve-0068c001-euttp/o83ANW8MYQW8G2oRf4eeB52cyG3ABQQiWgFfIA/?a=1233&bti=NEBzNTY6QGo6OjZALnAjNDQuYCMxNDNg&&bt=749&ft=td_Lr8QLodzR12Nv416qzIxRne1EHF_45SY&mime_type=video_mp4&rc=Zmk7aTdoOjszZDUzMzNoOkBpamdwdmw5cjZxOzMzZjczNUBgMDAuLTY0NS8xMS1fM2E1YSNrby1vMmRzL3BhLS1kMTNzcw%3D%3D&vvpl=1&l=20261002072233B02BC259EE528DC84245&btag=e0004d000", "thumbnail_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-useast2a-p-0037-euttp/ogwa5At7LzQxFiI1oHifBAoZtccBivI3IBByCH~tplv-tiktokx-cropcenter:500:800.jpeg?biz_tag=musically_video.video_cover&dr=10397&idc=no1a&ps=13740610&refresh_token=74733555&shcp=9b759fb9&shp=c1333099&t=4d5b0474&x-expires=1790946000&x-signature=PQSPaUw3rsDOcy%2BZK9VrEB9Z8bs%3D", "duration_seconds": 30.255 }, "author": { "username": "user_83a4f7", "display_name": "user_b74e08", "avatar_url": "https://example.com/avatars/user_6a0a05.png", "verified": false }, "engagement": { "views": 12605667, "likes": 1203752, "comments": 1740, "shares": 137145, "saves": 418119 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2026-06-22T17:32:25.000Z", "ext": { "music_id": "7654274017737739040", "author_id": "user_558467", "author_followers": 744116, "download_count": 21838, "region": "DZ", "published_at_epoch": 1782149545 } }, "computed": { "engagement_rate": 0.106511, "language": "en", "content_category": "food", "estimated_reach": 15126800, "relevance": { "p": 0.96, "sense": "target", "depth": 2.96, "spam": 0.17 }, "labels": null } }, { "post": { "id": "7690673524758924557", "url": "https://www.tiktok.com/@user_534aa6/video/7690673524758924557", "content": { "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "media_urls": "https://v45.tiktokcdn-eu.com/b38ef6974795af88f5a4e632476dd62c/6ac0ad77/video/tos/alisg/tos-alisg-ve-37c799-sg/ogwq3LEhi4SrBi89PRSCiQKxU6wrAEzIgaBJ3/?a=1233&bti=NEBzNTY6QGo6OjZALnAjNDQuYCMxNDNg&&bt=1335&ft=td_Lr8QLodzR12Nv416qzIxRne1EHF_45SY&mime_type=video_mp4&rc=aDg1ZjxoODY0Nmk4OWZoaUBpM3Y8NXE5cm1mZDMzZzczNEBeNDYtYDNgXi4xYjUyXjRfYSNlMHEyMmQ0MnFhLS1kMS9zcw%3D%3D&vvpl=1&l=20261002072233B02BC259EE528DC84245&btag=e00095000", "thumbnail_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oowqrLEJi4yrBi8EPRmCiDKhU6urAIzIgaBB3~tplv-tiktokx-cropcenter:500:800.jpeg?biz_tag=musically_video.video_cover&dr=10397&idc=no1a&ps=13740610&refresh_token=da5333f1&shcp=9b759fb9&shp=c1333099&t=4d5b0474&x-expires=1790946000&x-signature=7LtahFZ51VBnXD0CudxZEW7jXnk%3D", "duration_seconds": 61.068 }, "author": { "username": "user_534aa6", "display_name": "user_534aa6", "avatar_url": "https://example.com/avatars/user_4d78da.png", "verified": false }, "engagement": { "views": 7314181, "likes": 599577, "comments": 820, "shares": 94755, "saves": 214954 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2026-09-28T19:41:19.000Z", "ext": { "music_id": "7690673470694329102", "author_id": "user_eedff9", "author_followers": 1199802, "download_count": 5664, "region": "US", "published_at_epoch": 1790624479, "on_screen_texts": [ "crispy cheeseburger sauce ", "H O W T O M A K E" ] } }, "computed": { "engagement_rate": 0.095042, "language": "en", "content_category": "food", "estimated_reach": 8777017, "relevance": { "p": 0.96, "sense": "target", "depth": 2.98, "spam": 0.06 }, "labels": { "sponsored": { "p": 0.05, "disclosed": false, "undisclosed": false, "brand": null }, "intent": { "label": null, "confidence": 0.45, "buyer": false, "seller": 0.29, "fits_offer": null, "urgency": 0.22 }, "niche": { "label": "food_cooking", "confidence": 1, "taxonomy": "sc-niche-v1" } } } } ], "next_cursor": "sc2.eyJzIjoiaCIsImMiOiJzYzEuZXlKaklqb2lNekFpTENKeklqcGJJamMyTlRReU56TTVPVEExTXpNME16UTJOVGNpTENJM05qa3dOamN6TlRJME56VTRPVEkwTlRVM0lpd2lOelk0TXprMU1EWTBPVFF5TnpNMk5URTFNeUlzSWpjMk56ZzRPVFkwTURJeE5UazJOamcxTURJaUxDSTNOamM1TVRBMk1EUTBPRFl4TVRJek9EVTBJaXdpTnpZeU9EWTFOVFF6T0RreE1qa3dNRE0zTkNJc0lqYzJOREl5TkRZNU5Ea3pOVGN6TkRFNU9EUWlMQ0kzTmpneU56Z3lNREEyTmpBMU9USTFOalkwSWl3aU56WTROVFE0TURRMU5qUXdPVGN4TXprMU15SXNJamMyT0RZNU9UTTBNRFUzTVRZMk5EY3hPRGdpTENJM05qZzROemMzTVRZNE1EUTFOemc0TkRRNElpd2lOelkzTnpJME1UVTBNVEl6TVRrMU5USXhOQ0lzSWpjMk1UZzNNRGsyT0RZME9EZzVOakF5TmpraUxDSTNOamcwTXpBM01ERXlOekkwT0RNM05qWXlJaXdpTnpZM01UTXlNRFkzTXpRME9EVXhNamM0TVNJc0lqYzJOVE0xTURNM09EVTRPVGN4TlRFM05qWWlMQ0kzTmpNM05ESTVPREEyTWpjMU1qWTNPRFl6SWl3aU56WTNOVGN4TURreU16a3dNVGc0TVRZeU1pSXNJamMyTWpFeE5qUTJOekl5TlRRNE56STRNelFpTENJM05qa3dNVGd6TWpFMk1EWXhNak00TlRZd0lpd2lOelk0T0RBM05UTXdNREEyT0RBeE9UUTJPU0lzSWpjMk5qRTJOamd5TWpjeU5qUTFPVGN5TnpraUxDSTNOamcxTmpJME5qQTBOakV6T0RVMk5UTXdJaXdpTnpZM05qYzNOek00T0RBMk16RXdNREU0TWlJc0lqYzJPRGs1TmpreE9USTVOelUxT0RRMU5ETWlMQ0kzTkRNM01qUTBOemd3TmpjME9EYzROelV5SWl3aU56WTFNRGt4T1RFNE5UVTFNVE16TURVM09DSXNJamMyTmpBNE9UZ3dPVGsxTVRReE5qWTFOREVpTENJM05qZzROREUzTlRRMk56azNOakUyTkRFMklpd2lOelkyTWpjNU9UZ3pNalV6TmpNMU5EQTNPQ0pkZlEifQ", "total": null, "relevance": { "mode": "score", "topic_source": "query", "rows": 30, "scored": 18, "cached": 4, "kept": 30, "dropped": 0, "dropped_ids": [], "unjudged": 0, "too_short": 0, "threshold": 0.5, "extra_credits": 0, "methodology_version": "relevance/2", "origin": "default", "pending": 12, "pending_ids": [ "7684307012724837662", "7671320673448512781" ], "status": "partial" }, "labels": { "presets": [ "sponsored", "intent" ], "rows": 30, "labelled": 18, "cached": 7, "skipped": 0, "unjudged": 0, "dropped": 0, "dropped_ids": [], "extra_credits": 0, "methodology_version": "labels/1", "mode": "default", "status": "partial", "pending": 12, "pending_ids": [ "7654273990533434657", "7683950649427365153" ] }, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pYUNJc0ltTWlPaUp6WXpFdVpYbEtha2xxYjJsTmVrRnBURU5LZWtscWNHSkphbU15VGxSUmVVNTZUVFZQVkVFeFRYcE5NRTE2VVRKT1ZHTnBURU5KTTA1cWEzZE9hbU42VGxSSk1FNTZWVFJQVkVrd1RsUlZNMGxwZDJsT2VsazBUWHByTVUxRVdUQlBWRkY1VG5wTk1rNVVSVEZOZVVselNXcGpNazU2WnpSUFZGa3dUVVJKZUU1VWF6Sk9hbWN4VFVSSmFVeERTVE5PYW1NMVRWUkJNazFFVVRCUFJGbDRUVlJKZWs5RVZUQkphWGRwVG5wWmVVOUVXVEZPVkZGNlQwUnJlRTFxYTNkTlJFMHpUa05KYzBscVl6Sk9SRWw1VGtSWk5VNUVhM3BPVkdONlRrUkZOVTlFVVdsTVEwa3pUbXBuZVU1NlozbE5SRUV5VG1wQk1VOVVTVEZPYWxrd1NXbDNhVTU2V1RST1ZGRTBUVVJSTVU1cVVYZFBWR040VFhwck1VMTVTWE5KYW1NeVQwUlpOVTlVVFRCTlJGVXpUVlJaTWs1RVkzaFBSR2RwVEVOSk0wNXFaelJPZW1NelRWUlpORTFFVVRGT2VtYzBUa1JSTkVscGQybE9lbGt6VG5wSk1FMVVWVEJOVkVsNlRWUnJNVTVVU1hoT1EwbHpTV3BqTWsxVVp6Tk5SR3N5VDBSWk1FOUVaelZPYWtGNVRtcHJhVXhEU1ROT2FtY3dUWHBCTTAxRVJYbE9la2t3VDBSTk0wNXFXWGxKYVhkcFRucFpNMDFVVFhsTlJGa3pUWHBSTUU5RVZYaE5hbU0wVFZOSmMwbHFZekpPVkUweFRVUk5NMDlFVlRSUFZHTjRUbFJGTTA1cVdXbE1RMGt6VG1wTk0wNUVTVFZQUkVFeVRXcGpNVTFxV1ROUFJGbDZTV2wzYVU1NldUTk9WR040VFVScmVVMTZhM2ROVkdjMFRWUlplVTFwU1hOSmFtTXlUV3BGZUU1cVVUSk9la2w1VGxSUk5FNTZTVFJOZWxGcFRFTkpNMDVxYTNkTlZHZDZUV3BGTWsxRVdYaE5hazAwVGxSWmQwbHBkMmxPZWxrMFQwUkJNMDVVVFhkTlJFRXlUMFJCZUU5VVVUSlBVMGx6U1dwak1rNXFSVEpPYW1kNVRXcGplVTVxVVRGUFZHTjVUbnByYVV4RFNUTk9hbWN4VG1wSk1FNXFRVEJPYWtWNlQwUlZNazVVVFhkSmFYZHBUbnBaTTA1cVl6Tk9lazAwVDBSQk1rMTZSWGROUkVVMFRXbEpjMGxxWXpKUFJHczFUbXByZUU5VVNUVk9lbFV4VDBSUk1VNUVUV2xNUTBrelRrUk5NMDFxVVRCT2VtZDNUbXBqTUU5RVl6Uk9lbFY1U1dsM2FVNTZXVEZOUkd0NFQxUkZORTVVVlRGTlZFMTZUVVJWTTA5RFNYTkphbU15VG1wQk5FOVVaM2RQVkdzeFRWUlJlRTVxV1RGT1JFVnBURU5KTTA1cVp6Uk9SRVV6VGxSUk1rNTZhek5PYWtVeVRrUkZNa2xwZDJsT2Vsa3lUV3BqTlU5VVozcE5hbFY2VG1wTk1VNUVRVE5QUTBwa1psRWlmUSIsImUiOiJ0aWt0b2svc2VhcmNoIiwicCI6ImN1cnNvciJ9", "has_more": true, "page_size": 30 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T07:22:36.736Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/trending": { "get": { "summary": "Get TikTok trending feed", "description": "Returns a page of popular TikTok videos for a country, with view, like, comment, share and save counts, caption, author and thumbnail. Two feeds, chosen with `feed`. The default (`feed=global`) is TikTok's web trending feed fetched through a connection in `region`: `region` sets where the request comes from, not where the videos come from, and for most countries the feed is one worldwide pool. Measured 13/09/2026 over 12 calls in six countries, 22% of its videos were registered in the requested country (US 65%, BR 43%, GB 9%, FR 8%, JP 6%, DE 0%). It returns about 13 videos in 3 to 12 seconds. `feed=local` is the For You feed TikTok's app serves to a phone set to `region`, so most, not all, of its videos are from that country: 57% of videos on 10 served pages the same day (DE 52%, US 66%, GB 41%, JP 81%), and 51% were captioned in the country's main language. It returns a median of 24 videos (13 to 33 on 9 pages in 10), and 9 calls in 10 answer within 22 seconds (364 served pages, 18-19/10/2026). On about 1 local call in 11 (26 of 281 measured 14-17/10/2026) the supplier is throttled or times out and no video comes back: that returns 503 with credits refunded, and a retry a minute later usually succeeds. A local request never falls back to the global feed. Both feeds cost the same, carry no cursor, and return each video once. Every row carries `ext.region`, the country the video is registered to, so filter on it when you need only that country; local rows also carry `ext.content_language`, TikTok's own caption-language tag. `post.ext.matched_song_id` is the catalogue song TikTok matched the row's sound to, present when it made a match: an official clip and the original sounds creators upload with it have different `post.ext.music_id` values and one `matched_song_id`, so group on it to count a song's uses (it is not a clipId for `/v1/tiktok/song/videos`).", "tags": [ "tiktok" ], "operationId": "get_tiktok_trending", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "parameters": [ { "name": "region", "in": "query", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g., US, GB, DE). On the default feed it sets the country the request is routed through and does not filter videos; with `feed=local` it sets the country the For You feed is built for. Either way, check `ext.region` on each row for the country a video is actually from.", "schema": { "type": "string" }, "example": "US" }, { "name": "trim", "in": "query", "required": false, "description": "Accepted for compatibility; it has no effect with `feed=local`.", "schema": { "type": "boolean" } }, { "name": "feed", "in": "query", "required": false, "description": "`global` (default): the web trending feed routed through `region`, mostly worldwide content, about 13 videos in 3 to 12 seconds. `local`: the For You feed for a phone in `region`, most videos from that country, a median of 24 videos with 9 calls in 10 answering within 22 seconds, and a refunded 503 when none come back.", "schema": { "type": "string", "enum": [ "global", "local" ] } }, { "name": "since", "in": "query", "required": false, "description": "Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.", "schema": { "type": "string" } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/trending" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical post wrappers ({ post, computed })", "items": { "type": "object", "description": "Canonical post wrapper", "properties": { "post": { "type": "object", "description": "Canonical Post object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "integer", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "integer", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "integer", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "integer", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "integer", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "integer", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "string", "null" ], "description": "Leaf at computed.labels" }, "labels_evidence": { "type": [ "string", "null" ], "description": "Leaf at computed.labels_evidence" } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/trending", "data": { "items": [ { "post": { "id": "7682049568975932702", "url": "https://www.tiktok.com/@user_ef4bc4/video/7682049568975932702", "content": { "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "media_urls": [ "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-i-photomode-tx2/b5d243cd1e17487e8aa85aedec348a33~tplv-photomode-sr-vqe2-new:1440:0:1080:0:q75.jpeg?dr=10952&refresh_token=2a8eb8de&x-expires=1792242000&x-signature=tn8wMg1ATV4g%2ByST%2BpI4o4L%2BzQw%3D&t=5897f7ec&ps=28cf8ac7&shp=d05b14bd&shcp=1a816805&idc=useast5&s=FEED&biz_tag=tt_photomode&sc=image" ], "thumbnail_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-i-photomode-tx2/b5d243cd1e17487e8aa85aedec348a33~tplv-photomode-image-cover:640:0:q70.webp?dr=12229&refresh_token=a2b32c0d&x-expires=1792242000&x-signature=0bt9TVezhwQ2A3yzOq2dRxKPRMY%3D&t=5897f7ec&ps=d5b8ac02&shp=d05b14bd&shcp=1a816805&idc=useast5&s=FEED&biz_tag=tt_photomode&sc=cover", "duration_seconds": 0 }, "author": { "username": "user_ef4bc4", "display_name": "user_4cf053", "avatar_url": "https://example.com/avatars/user_783baf.png", "verified": false }, "engagement": { "views": 3253405, "likes": 70388, "comments": 1892, "shares": 23013, "saves": 36428 }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-05T13:56:12.000Z", "ext": { "music_id": "6814378834477975553", "author_id": "user_29dfab", "region": "US", "published_at_epoch": 1788616572 } }, "computed": { "engagement_rate": 0.02929, "language": "en", "content_category": "other", "estimated_reach": 3904086 } }, { "post": { "id": "7677659988789103902", "url": "https://www.tiktok.com/@user_8a8702/video/7677659988789103902", "content": { "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "media_urls": "https://v16m.tiktokcdn-us.com/7200fde1f54a7b3ac3b3dcf15359dec3/6ac0015d/video/tos/useast8/tos-useast8-ve-0068c002-tx2/okqBUMjDiq5QE2iA1WXA7hkPuNyIAfCRMIijd8/?a=1233&bti=OHYpOTY0Zik3OjlmOm01MzE6ZDQ0MDo%3D&&bt=1216&ft=arR-Iqx4m3XPD12Pa4MI3wU3B4zKaeF~O5&mime_type=video_mp4&rc=aWU7NTs0M2U4NzczZjpoaUBpM3FpOmw5cnk7ZDMzaTczNEBfNTZgLy9gXzExNWJjMS4tYSNebGNrMmQ0YTNhLS1kMTJzcw%3D%3D&vvpl=1&l=20261002130753BA797C81DDCD61F02618&btag=e00090000", "thumbnail_url": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oMKB7A1AiCuAIviA1yaAEhkP4N0IBfCRMEiLpn~tplv-tiktokx-shrink_ep:640:640:q78.jpeg?dr=8592&refresh_token=aa8c83c9&x-expires=1791032400&x-signature=Brow6cNgUtLAHFGTBIaBI63oBb0%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=1a816805&idc=useast5&biz_tag=tt_video&s=FEED&sc=cover", "duration_seconds": 81 }, "author": { "username": "user_8a8702", "display_name": "user_4c407b", "avatar_url": "https://example.com/avatars/user_f9f9c2.png", "verified": false }, "engagement": { "views": 20024442, "likes": 234869, "comments": 8723, "shares": 23981, "saves": 68392 }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-08-24T18:02:23.000Z", "ext": { "music_id": "7677659961165499167", "author_id": "user_491ac5", "region": "US", "published_at_epoch": 1787594543 } }, "computed": { "engagement_rate": 0.013362, "language": "en", "content_category": "entertainment", "estimated_reach": 24029330 } } ], "total": null, "dropped": 0 }, "credits_used": 5, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": null, "has_more": false, "page_size": 11 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T13:07:58.191Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/search/hashtag": { "get": { "summary": "Search TikTok by hashtag", "description": "Searches TikTok for videos under a specific hashtag. Returns matching videos with engagement metrics and author info. `post.ext.region` is the ISO country TikTok registers each video to, when the source sends one. Pagination: send `pagination.next_cursor` back as `cursor` while `pagination.has_more` is true. Each page aims at 25 or more videos the walk has not returned: when `since`/`until` or the walk's de-duplication removes rows, the page reads further on before it is served, at no extra credits. A shorter page is normal near the end of the hashtag's videos.", "tags": [ "tiktok" ], "operationId": "get_tiktok_search_hashtag", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 5, "x-credit-cost-formula": "1 credit per page. The default labels (sponsored, intent, niche) are free. label=mention, quality, ai_style, ai_written, injection, or label=intent with offer=, holds 4 extra credits and refunds down to 1 credit per started 25 posts that were newly judged: posts already labelled are free, a page where nothing could be judged refunds the whole extra, and a cached page is free. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total. With `seen`, a page's price falls with its share of rows you already received under that id; credits for joined data (`include=`) are never discounted.", "parameters": [ { "name": "hashtag", "in": "query", "required": true, "description": "Hashtag to search for without the # symbol", "schema": { "type": "string" }, "example": "fyp" }, { "name": "region", "in": "query", "required": false, "description": "Region the proxy will be set to. Note: this isn't going to grab you all tiktoks from this region, you're just setting the proxy there.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor to get more videos. Get 'cursor' from previous response.", "schema": { "type": "integer" } }, { "name": "trim", "in": "query", "required": false, "description": "Accepted for compatibility; the response is already the canonical shape, so this flag has no effect.", "schema": { "type": "boolean" } }, { "name": "label", "in": "query", "required": false, "description": "Optional CSV of SocialCrawl labels to add to every post. Without this param every page already carries sponsored, intent and niche, free; label= adds the labels you name to them (the defaults keep running). sponsored, intent and niche are free when asked for too; mention, quality, ai_style, intent with offer=, and injection add 1 credit per started 25 newly judged posts. judgments=off (or label=none) turns the default labels off. sponsored: is the post a paid or gifted promotion (p, 0 to 1), did it carry a disclosure marker such as #ad or 광고 (disclosed), is it likely paid with no marker (undisclosed), and which of the accounts it mentions does it promote (brand, or null). These are signals to review, never a finding. mention (needs brand=): is the post about that brand rather than something that shares its name (about_brand, 0 to 1), how it feels about the brand on five levels (sentiment_level 0 to 4 and sentiment_score 0 to 1, null when the post is not about the brand), is it sarcastic, which aspect it talks about (taste_or_quality, price_or_value, availability_or_delivery, health_or_safety, advertising_or_campaign, customer_service, none), and did the author buy or use it (first_hand). intent: what the author is mainly doing (label: asking_for_recommendation, comparing_options, switching_away, complaining, promoting, news_or_discussion, other, or null when unsure, with confidence), whether they read as a potential buyer rather than a seller (buyer, seller), how pressing the need is (urgency, 0 to 3), and, when you pass offer=, whether your offer would plausibly help them (fits_offer). niche: which of the 33 niches of the published taxonomy sc-niche-v1 the caption belongs to, or personal_no_niche, or other (label, confidence, taxonomy), with label null when the caption is too thin to tell or the pick is unsure. It reads the caption only, not the video. quality: how much checkable detail the caption carries (fact_density 0 to 3), whether it mainly asks for likes, replies, shares, follows or tags (engagement_bait, 0 to 1), whether it is written to provoke anger as a way to get engagement (rage_bait, 0 to 1; about the writing, never the side taken), whether it only repeats someone else's news or view (secondhand, 0 to 1), and what the post is mainly doing (post_aim: inform, opinion, sell, entertain, provoke, other). exclude=engagement_bait drops posts whose engagement_bait is 0.8 or higher. ai_style: writing patterns common in AI-generated text, judged on the text alone. It does not say who wrote the post, and a person who writes in this style is flagged too. Six patterns are judged, each a probability (0 to 1): binary_contrast (\"This is not X. It's Y.\"), faux_insight (\"Here's what nobody tells you\" and throat-clearing openers), colon_reveal (\"The best part: it learns.\"), profound_kicker (ends on an aphorism or mic-drop line), puffery (\"marks a pivotal moment\", \"highlighting the importance of\") and rhetorical_setup (\"What if I told you\", a question the post answers itself, \"Not a X. Not a Y. A Z.\"). Four are counted in the text: slop_words (words and phrases such as delve, leverage, robust, game changer, at the end of the day), em_dashes, emoji_bullets (lines that start with an emoji or a symbol bullet) and one_line_paragraphs (paragraphs that are one short line). pattern_count is how many patterns are present (a judged pattern at 0.8 or higher, slop_words 1 or more, em_dashes 2 or more, emoji_bullets 2 or more, one_line_paragraphs 5 or more) and markers lists their names, comma-separated. A post with less than about eight words of text is only counted, with every judged pattern 0. The judged patterns read the first 400 and the last 150 characters of a long post, and the counts read the whole post. exclude=ai_style drops posts with 2 or more patterns. ai_written: how likely the post was written by an AI model, from SocialCrawl's own text classifier, reading the opening of the post (about 1,000 characters): p (0 to 1, calibrated), level (likely (p 0.95 or higher), possible (p 0.71 or higher) or unlikely) and model (the model name; a new name means a new scale). A post under 8 words is too short to read: p null, level too_short. It is a probability, not proof: a person can be flagged and an AI-written post can pass, and the shorter the post the less certain it is. exclude=ai_written drops likely posts. injection flags text that addresses an AI system and tries to direct it (flagged, p); it never drops or rewrites a row. A post that could not be judged carries labels: null. Posts already labelled for anyone are free, and so is a cached page. data.labels reports what was judged and billed.", "schema": { "type": "string" } }, { "name": "exclude", "in": "query", "required": false, "description": "Optional CSV (engagement_bait, ai_style, ai_written). engagement_bait, only with label=quality, drops posts whose engagement_bait probability is 0.8 or higher. ai_style, only with label=ai_style, drops posts that show 2 or more of its writing patterns (pattern_count 2 or higher). ai_written, only with label=ai_written, drops posts whose level is likely (p 0.95 or higher), or whose p reaches your ai_written_threshold; a post too short to read is never dropped. Dropped posts are listed in data.labels.dropped_ids. A post that could not be judged is never dropped.", "schema": { "type": "string" } }, { "name": "ai_written_threshold", "in": "query", "required": false, "description": "Optional, only with label=ai_written and exclude=ai_written. The p (0 to 1) at which exclude=ai_written drops a post. Default 0.95 (level likely). 0.71 also drops possible posts: more AI posts go, and more posts by people with them.", "schema": { "type": "string" } }, { "name": "brand", "in": "query", "required": false, "description": "Required by label=mention, ignored otherwise. The brand or product the posts are judged against, up to 300 characters, for example brand=Buldak. Without it label=mention is skipped with the warning label_mention_needs_brand and is not billed.", "schema": { "type": "string" } }, { "name": "brand_description", "in": "query", "required": false, "description": "Optional, with label=mention. One plain sentence saying what the brand is, for example brand_description=Samyang's spicy instant noodle brand. Use it when the name is also an ordinary word or another company's name.", "schema": { "type": "string" } }, { "name": "offer", "in": "query", "required": false, "description": "Optional, with label=intent. One or two plain sentences saying what you sell, up to 300 characters, for example offer=A web design agency that builds websites for small businesses. Adds fits_offer to every post; without it fits_offer is null.", "schema": { "type": "string" } }, { "name": "judgments", "in": "query", "required": false, "description": "Optional, on (the default) or off. By default every row gains free SocialCrawl judgments (computed.labels, and computed.relevance on search endpoints), reported in data.labels (mode default) and data.relevance (origin default), each with a status (complete, partial or skipped) and pending: the rows still being judged when the page was sent, which carry null now and are filled on your next call or cached read. Default judgments never add credits, never change an existing field, and never drop or reorder a row. off returns the page exactly as before, with none of those keys. label=none does the same.", "schema": { "type": "string", "enum": [ "on", "off" ] } }, { "name": "dry_run", "in": "query", "required": false, "description": "Optional. When 1, return a cost preview for this labelled or relevance-filtered request without fetching the page or judging any row. data.estimate reports rows_expected, rows_cached, label_credits_min, label_credits_max and base_credits. 0 credits charged.", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "label_evidence", "in": "query", "required": false, "description": "Optional, only with label=. When 1, every labelled row also carries computed.labels_evidence. = { quote, sentence_index }: the sentence in the row that most clearly shows the label, copied verbatim. Absent or null when no single sentence shows it.", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "fit", "in": "query", "required": false, "description": "Optional. When goal, keep the rows and fields needed for the goal you pass in goal= (plus any that are uncertain, and the first and last), and replace the rest with a stub. data.held_back lists the held ids and a recall id that re-reads the full page from cache at no extra charge. Without this param the page is unchanged.", "schema": { "type": "string", "enum": [ "goal" ] } }, { "name": "goal", "in": "query", "required": false, "description": "Required by fit=goal. What you are trying to do, in your own words, up to 300 characters.", "schema": { "type": "string" } }, { "name": "fit_tokens", "in": "query", "required": false, "description": "Optional, only with fit=goal. Soft cap on how much of the page to keep, in tokens. Uncertain blocks and the first and last block are kept even if they exceed it.", "schema": { "type": "integer" } }, { "name": "since", "in": "query", "required": false, "description": "Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.", "schema": { "type": "string" } }, { "name": "min_views", "in": "query", "required": false, "description": "Keep only rows with at least this many views (`post.engagement.views`). A row whose view count is unknown is discarded, so every returned row meets the floor. Filtering runs on our side after each page is fetched, so every page walked is billed as usual; `data.walk.discarded` counts what was removed and why. Each page is its own entry in `GET /v1/credits/transactions`, under the page's request id listed in `data.walk.request_ids`.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "max_age_days", "in": "query", "required": false, "description": "Keep only rows published within this many days (`post.published_at`), 1 to 3650. A row with no date is discarded. Filtering runs on our side after each page is fetched, so every page walked is billed as usual; `data.walk.discarded` counts what was removed and why. Each page is its own entry in `GET /v1/credits/transactions`, under the page's request id listed in `data.walk.request_ids`.", "schema": { "type": "integer", "minimum": 1, "maximum": 3650 } }, { "name": "sort_rows", "in": "query", "required": false, "description": "`views`: return the kept rows ordered by view count, highest first, across every page walked. Rows without a view count go last.", "schema": { "type": "string", "enum": [ "views" ] } }, { "name": "max_pages", "in": "query", "required": false, "description": "1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them (after any filter). Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "max_items", "in": "query", "required": false, "description": "1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows (after any filter), then stop with `data.walk.stopped: \"max_items\"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`\"time_budget\"`): send the returned cursor with the same params to continue.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "max_credits", "in": "query", "required": false, "description": "1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: \"max_credits\"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "seen", "in": "query", "required": false, "description": "An id you choose (1 to 64 letters, digits, `.`, `_` or `-`). Rows your account already received under the same `seen` id are removed from the page, and the page price falls with the share of repeats: page credits x new rows / rows on the page, rounded up, so a page of nothing but repeats is free. Only the page's own price is discounted: credits for joined data (`include=`) are charged only for rows you have not received, and are never discounted. The memory lasts 24 hours from the last call that used the id, holds row ids only, and is private to your account. Use one id across a set of related searches; `data.walk.repeats` counts what was removed.", "schema": { "type": "string" } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/search/hashtag" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical post wrappers ({ post, computed })", "items": { "type": "object", "description": "Canonical post wrapper", "properties": { "post": { "type": "object", "description": "Canonical Post object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "integer", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "integer", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "integer", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "integer", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "integer", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "integer", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "string", "null" ], "description": "Leaf at computed.labels" }, "labels_evidence": { "type": [ "string", "null" ], "description": "Leaf at computed.labels_evidence" } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/search/hashtag", "data": { "items": [ { "post": { "id": "7691965619624955158", "url": "https://www.tiktok.com/@user_5a907c/video/7691965619624955158", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://v45.tiktokcdn-eu.com/6c391a49e871648ab0dad81d004f5e44/6ac0ae60/video/tos/no1a/tos-no1a-ve-0068c001-no/o4IVfgGuQsMID1MWeiAAIJILHVflEG5fhAeNgW/?a=1233&bti=Ojs2NGYpQHM6OjZALjU2OmQvcCMxNDNg&&bt=1127&ft=ERfCrmZWD0~u12NvyJ6qzIxRMj8Zi3_45SY&mime_type=video_mp4&rc=Njg3PDo4aDw2OGU4OWQ7NUBpanZpa205cnZvZDMzbzczNUBhMzE1LmI2NTUxYzM0LTE2YSNlYi00MmRrY3NhLS1kMTFzcw%3D%3D&vvpl=1&l=202610020727164014D92F5CFFFEE6A7C6&btag=e000b5000&sp_exp=hash_v0", "thumbnail_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-no1a-p-0037-no/oMGNMfIVH4eThfggiIflWiAIGeAlLsD5uMzVVQ~tplv-tiktokx-origin.image?dr=1347&refresh_token=db533537&x-expires=1791010800&x-signature=M3EGUpoNs99DxsJgPmk%2FuzeZ6qc%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=c0f880ed&idc=no1a&biz_tag=tt_video&s=CHALLENGE_AWEME&sc=cover", "duration_seconds": 11.4 }, "author": { "username": "user_5a907c", "display_name": "user_befc5a", "avatar_url": "https://example.com/avatars/user_6cedcd.png", "verified": false }, "engagement": { "views": 118, "likes": 22, "comments": 10, "shares": 4, "saves": 0 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2026-10-02T07:15:20.000Z", "ext": { "music_id": "7691965654240447254", "author_id": "user_79a34d", "download_count": 0, "published_at_epoch": 1790925320 } }, "computed": { "engagement_rate": 0.305085, "language": null, "content_category": "other", "estimated_reach": 142, "labels": null } }, { "post": { "id": "7691966126997261590", "url": "https://www.tiktok.com/@user_21333d/video/7691966126997261590", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://v45.tiktokcdn-eu.com/498de562048c7f6ca92c064e96db06fc/6ac0ae5f/video/tos/no1a/tos-no1a-ve-0068c001-no/oQ4fjTAfeAQOWNFjgGGqmoGEWIWQLRazfrCIsx/?a=1233&bti=Ojs2NGYpQHM6OjZALjU2OmQvcCMxNDNg&&bt=952&ft=ERfCrmZWD0~u12NvyJ6qzIxRMj8Zi3_45SY&mime_type=video_mp4&rc=Njc2Zjs7OGRkOzwzNmdpZEBpMzxrdnY5cmZvZDMzbzczNUAuMmFiXjVfXjAxYF5fYzFeYSNlZ29jMmRjZ3NhLS1kMTFzcw%3D%3D&vvpl=1&l=202610020727164014D92F5CFFFEE6A7C6&btag=e000b5000&sp_exp=hash_v0", "thumbnail_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-no1a-p-0037-no/ogqlQfTRAGICzAc4EWaGeLoxNWQljQmfGrf43I~tplv-tiktokx-origin.image?dr=1347&refresh_token=160061dd&x-expires=1791010800&x-signature=88ZkwZ4tua5igBfzDV%2BN6jXcvC0%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=c0f880ed&idc=no1a&biz_tag=tt_video&s=CHALLENGE_AWEME&sc=cover", "duration_seconds": 10.35 }, "author": { "username": "user_21333d", "display_name": "user_3fdbeb", "avatar_url": "https://example.com/avatars/user_3fba9d.png", "verified": false }, "engagement": { "views": 191, "likes": 40, "comments": 0, "shares": 0, "saves": 4 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2026-10-02T07:17:17.000Z", "ext": { "music_id": "7285850014168533802", "author_id": "user_4de9c2", "download_count": 0, "published_at_epoch": 1790925437, "on_screen_texts": [ "pov: It’s a FRIDAY morning , it’s cold asf, had the best sleep , best dream , but somehow woke up with back pain and have no motivation to go to work/school\n" ] } }, "computed": { "engagement_rate": 0.209424, "language": null, "content_category": "other", "estimated_reach": 229, "labels": null } } ], "next_cursor": "sc2.eyJzIjoiaCIsImMiOiJzYzEuZXlKaklqb2lNakFpTENKeklqcGJJamMyT1RFNU5qVTJNVGsyTWpRNU5UVXhOVGdpTENJM05qa3hPVFkyTVRJMk9UazNNall4TlRrd0lpd2lOelk0T0RFM01qQXlOamN5TURJeE1ERTVOaUlzSWpjMk9URTVOalV5TVRBME16STNPRFUyT0RZaUxDSTNOamcxT0RNd09UTTFPVGsyTVRVM01qRTNJaXdpTnpNeU1qUTNPREV3Tmprek1Ua3lOREkxTlNJc0lqYzJOVGM1TlRRd01URXpPREk1TkRJNU9Ea2lMQ0kzTmpreE9UWTFOelF4TXprNE1ERTVNek14SWl3aU56WTVNVGsyTnpZeU1qWXhPRGcwTkRRek9DSXNJamMyT1RFNU5qWTFNVEF3TnpFek1UazRNekFpTENJM05qa3hPVFkxT0RJMk5UTTBNRGd6T0RZeUlpd2lOelk1TVRrMk5EYzBNVGt3TXpnMk16QTNNeUlzSWpjMk9URTVOamN4TURVNU1UUXhOakkwTlRRaUxDSTNOamt4T1RZMU16SXdNVFEzTXpnNU56RTRJaXdpTnpZNU1UazJOVGMzTXpjNU1EWXlPVEUwTWlJc0lqYzJPVEU1TmpZNE16WXpNek0yTWpnMk9UUWlYWDAifQ", "total": null, "labels": { "presets": [ "sponsored", "intent" ], "rows": 16, "labelled": 3, "cached": 1, "skipped": 1, "unjudged": 0, "dropped": 0, "dropped_ids": [], "extra_credits": 0, "methodology_version": "labels/1", "mode": "default", "status": "partial", "pending": 12, "pending_ids": [ "7691965619624955158", "7691966126997261590" ] }, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pYUNJc0ltTWlPaUp6WXpFdVpYbEtha2xxYjJsTmFrRnBURU5LZWtscWNHSkphbU15VDFSRk5VNXFWVEpOVkdzeVRXcFJOVTVVVlhoT1ZHZHBURU5KTTA1cWEzaFBWRmt5VFZSSk1rOVVhek5OYWxsNFRsUnJkMGxwZDJsT2VsazBUMFJGTTAxcVFYbE9hbU41VFVSSmVFMUVSVFZPYVVselNXcGpNazlVUlRWT2FsVjVUVlJCTUUxNlNUTlBSRlV5VDBSWmFVeERTVE5PYW1jeFQwUk5kMDlVVFRGUFZHc3lUVlJWTTAxcVJUTkphWGRwVG5wTmVVMXFVVE5QUkVWM1RtcHJlazFVYTNsT1JFa3hUbE5KYzBscVl6Sk9WR00xVGxSUmQwMVVSWHBQUkVrMVRrUkpOVTlFYTJsTVEwa3pUbXByZUU5VVdURk9lbEY0VFhwck5FMUVSVFZOZWsxNFNXbDNhVTU2V1RWTlZHc3lUbnBaZVUxcVdYaFBSR2N3VGtSUmVrOURTWE5KYW1NeVQxUkZOVTVxV1RGTlZFRjNUbnBGZWsxVWF6Uk5la0ZwVEVOSk0wNXFhM2hQVkZreFQwUkpNazVVVFRCTlJHZDZUMFJaZVVscGQybE9lbGsxVFZSck1rNUVZekJOVkd0M1RYcG5NazE2UVROTmVVbHpTV3BqTWs5VVJUVk9hbU40VFVSVk5VMVVVWGhPYWtrd1RsUlJhVXhEU1ROT2FtdDRUMVJaTVUxNlNYZE5WRkV6VFhwbk5VNTZSVFJKYVhkcFRucFpOVTFVYXpKT1ZHTXpUWHBqTlUxRVdYbFBWRVV3VFdsSmMwbHFZekpQVkVVMVRtcFpORTE2V1hwTmVrMHlUV3BuTWs5VVVXbFlXREFpZlEiLCJlIjoidGlrdG9rL3NlYXJjaC9oYXNodGFnIiwicCI6ImN1cnNvciJ9", "has_more": true, "page_size": 16 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T07:27:19.420Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/search/top": { "get": { "summary": "TikTok top search results", "description": "Returns the top-ranked videos for a keyword query on TikTok. Rows are posts only: account search lives at `/v1/tiktok/search/users` and sound search at `/v1/tiktok/search/music`. Filter by `publish_time` (also accepted as `date_posted`, the spelling `/v1/tiktok/search` uses) and `sort_by`. Every row carries `post.ext.region`, the country the video is registered to. The `region` request parameter only sets the proxy; filter on `post.ext.region` when you need one country. `post.ext.matched_song_id` is the catalogue song TikTok matched the row's sound to, present when it made a match: an official clip and the original sounds creators upload with it have different `post.ext.music_id` values and one `matched_song_id`, so group on it to count a song's uses (it is not a clipId for `/v1/tiktok/song/videos`).", "tags": [ "tiktok" ], "operationId": "get_tiktok_search_top", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search keyword or phrase", "schema": { "type": "string" }, "example": "dance challenge" }, { "name": "publish_time", "in": "query", "required": false, "description": "Time Frame TikTok was posted", "schema": { "type": "string", "enum": [ "yesterday", "this-week", "this-month", "last-3-months", "last-6-months", "all-time" ] } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort by", "schema": { "type": "string", "enum": [ "relevance", "most-liked", "date-posted" ] } }, { "name": "region", "in": "query", "required": false, "description": "Sets the proxy country (ISO 3166-1 alpha-2). It does not filter the page to that country. Each row already carries post.ext.region, the country the video is registered to; filter on that leaf when you need only one country.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor to get more videos. Get 'cursor' from previous response.", "schema": { "type": "integer" } }, { "name": "since", "in": "query", "required": false, "description": "Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.", "schema": { "type": "string" } }, { "name": "min_views", "in": "query", "required": false, "description": "Keep only rows with at least this many views (`post.engagement.views`). A row whose view count is unknown is discarded, so every returned row meets the floor. Filtering runs on our side after each page is fetched, so every page walked is billed as usual; `data.walk.discarded` counts what was removed and why. Each page is its own entry in `GET /v1/credits/transactions`, under the page's request id listed in `data.walk.request_ids`.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "max_age_days", "in": "query", "required": false, "description": "Keep only rows published within this many days (`post.published_at`), 1 to 3650. A row with no date is discarded. Filtering runs on our side after each page is fetched, so every page walked is billed as usual; `data.walk.discarded` counts what was removed and why. Each page is its own entry in `GET /v1/credits/transactions`, under the page's request id listed in `data.walk.request_ids`.", "schema": { "type": "integer", "minimum": 1, "maximum": 3650 } }, { "name": "country", "in": "query", "required": false, "description": "Comma-separated two-letter ISO 3166-1 codes, for example `US,GB`. Keep only videos TikTok registers to one of these countries (`post.ext.region`); a row with no country is discarded. This filters rows; it does not change where the search runs (that is `region`). Filtering runs on our side after each page is fetched, so every page walked is billed as usual; `data.walk.discarded` counts what was removed and why. Each page is its own entry in `GET /v1/credits/transactions`, under the page's request id listed in `data.walk.request_ids`.", "schema": { "type": "string" } }, { "name": "exclude_country", "in": "query", "required": false, "description": "Comma-separated two-letter ISO 3166-1 codes, for example `IN`. Discard videos TikTok registers to any of these countries (`post.ext.region`); a row with no country is kept. Filtering runs on our side after each page is fetched, so every page walked is billed as usual; `data.walk.discarded` counts what was removed and why. Each page is its own entry in `GET /v1/credits/transactions`, under the page's request id listed in `data.walk.request_ids`.", "schema": { "type": "string" } }, { "name": "sort_rows", "in": "query", "required": false, "description": "`views`: return the kept rows ordered by view count, highest first, across every page walked. Rows without a view count go last.", "schema": { "type": "string", "enum": [ "views" ] } }, { "name": "max_pages", "in": "query", "required": false, "description": "1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them (after any filter). Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "max_items", "in": "query", "required": false, "description": "1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows (after any filter), then stop with `data.walk.stopped: \"max_items\"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`\"time_budget\"`): send the returned cursor with the same params to continue.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "max_credits", "in": "query", "required": false, "description": "1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: \"max_credits\"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "seen", "in": "query", "required": false, "description": "An id you choose (1 to 64 letters, digits, `.`, `_` or `-`). Rows your account already received under the same `seen` id are removed from the page, and the page price falls with the share of repeats: page credits x new rows / rows on the page, rounded up, so a page of nothing but repeats is free. Only the page's own price is discounted: credits for joined data (`include=`) are charged only for rows you have not received, and are never discounted. The memory lasts 24 hours from the last call that used the id, holds row ids only, and is private to your account. Use one id across a set of related searches; `data.walk.repeats` counts what was removed.", "schema": { "type": "string" } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/search/top" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical post wrappers ({ post, computed })", "items": { "type": "object", "description": "Canonical post wrapper", "properties": { "post": { "type": "object", "description": "Canonical Post object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "integer", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "integer", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "integer", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "integer", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "integer", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "integer", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "string", "null" ], "description": "Leaf at computed.labels" }, "labels_evidence": { "type": [ "string", "null" ], "description": "Leaf at computed.labels_evidence" } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/search/top", "data": { "items": [ { "post": { "id": "7682447635168447776", "url": "https://www.tiktok.com/@user_7bc94d/video/7682447635168447776", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://v19.tiktokcdn-us.com/43ce6bd9074a3a4211809244828e07b6/6abfb376/video/tos/useast2a/tos-useast2a-ve-0068-euttp/o8NhGDfEfQnJqs0miIBPRYA4bKQkFDEKDtsYF7/?a=1233&bti=NEBzNTY6QGo6OjZALnAjNDQuYCMxNDNg&&bt=651&ft=BIcq8V~3wUxl7K2gUtIvk84jWLpij8f.QjKJpPi8gG0P3-I&mime_type=video_mp4&rc=MzxkZDw7Ojo5MzQzaDVnNkBpMzY5a3A5cnVyZDMzZjczNUAuMzU0YS8wNl8xNjZgYF5jYSNhbDVsMmQ0NGJhLS1kMTNzcw%3D%3D&vvpl=1&l=20261002072721C14171D7C02894FE5FF8&btag=e000e0000", "thumbnail_url": "https://p19-common-sign.tiktokcdn-us.com/tos-useast2a-p-0037-euttp/o4AAxQAd7ZVAY3xExFIeFLOIjGtG2gLMDIeEf6~tplv-tiktokx-cropcenter:500:800.jpeg?biz_tag=musically_video.video_cover&dr=9638&idc=useast5&ps=13740610&refresh_token=650d6607&shcp=9b759fb9&shp=c1333099&t=4d5b0474&x-expires=1790946000&x-signature=VPQw%2FuraiRljZ%2BY%2F8VlqftjjoFk%3D", "duration_seconds": 573.167 }, "author": { "username": "user_7bc94d", "display_name": "user_d4d765", "avatar_url": "https://example.com/avatars/user_4035a9.png", "verified": false }, "engagement": { "views": 119585, "likes": 5447, "comments": 36, "shares": 64, "saves": 846 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2026-09-06T15:40:32.000Z", "ext": { "music_id": "7678400758038956832", "author_id": "user_41369b", "author_followers": 142216, "download_count": 49, "region": "DE", "published_at_epoch": 1788709232 } }, "computed": { "engagement_rate": 0.046385, "language": null, "content_category": "other", "estimated_reach": 143502 } }, { "post": { "id": "7686446516088655126", "url": "https://www.tiktok.com/@user_fc183f/video/7686446516088655126", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://v19.tiktokcdn-us.com/fbfa22bb34d071729e5b245f3b41cdd9/6abfb147/video/tos/no1a/tos-no1a-ve-0068c001-no/o8ErJkwVfAINE86XQBI1LnAhviCyiCw35dBEx2/?a=1233&bti=NEBzNTY6QGo6OjZALnAjNDQuYCMxNDNg&&bt=1015&ft=BIcq8V~3wUxl7K2gUtIvk84jWLpij8f.QjKJpPi8gG0P3-I&mime_type=video_mp4&rc=aTs6NTU2O2dlZmU6NGhlPEBpajdtbHA5cjd1ZDMzbzczNUBhYTQ2MC0xNjIxMTNfX19jYSNkY2xwMmRzcGlhLS1kMTFzcw%3D%3D&vvpl=1&l=20261002072721C14171D7C02894FE5FF8&btag=e000b0000", "thumbnail_url": "https://p19-common-sign.tiktokcdn-us.com/tos-no1a-p-0037-no/ow2Eor8idJEkVOm1A5BIIvLiSfywYmCyCBhAw3~tplv-tiktokx-cropcenter:500:800.jpeg?biz_tag=musically_video.video_cover&dr=9638&idc=useast5&ps=13740610&refresh_token=c845c3be&shcp=9b759fb9&shp=c1333099&t=4d5b0474&x-expires=1790946000&x-signature=1MZWwhRbEasW3ld3uFxB4PH4gzk%3D", "duration_seconds": 14.234 }, "author": { "username": "user_fc183f", "display_name": "user_db74c9", "avatar_url": "https://example.com/avatars/user_445983.png", "verified": false }, "engagement": { "views": 3565786, "likes": 722578, "comments": 870, "shares": 26612, "saves": 39082 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2026-09-17T10:18:18.000Z", "ext": { "music_id": "7644514508602018578", "author_id": "user_8a1324", "author_followers": 213276, "download_count": 1073, "region": "NO", "published_at_epoch": 1789640298, "on_screen_texts": [ "Pov: you didnt wanna do THAT part" ] } }, "computed": { "engagement_rate": 0.210349, "language": null, "content_category": "other", "estimated_reach": 4278943 } } ], "next_cursor": "sc2.eyJzIjoiaCIsImMiOiJzYzEuZXlKaklqb2lNekFpTENKeklqcGJJamMyT0RJME5EYzJNelV4TmpnME5EYzNOellpTENJM05qZzJORFEyTlRFMk1EZzROalUxTVRJMklpd2lOelk1TVRNM05ESTNOakEzTURRME5ETXdNU0lzSWpjMk9URTBNRFkxTVRnNE5ESTVNakF5TWpNaUxDSTNOamt4TXpBNU5UZzJOVEF4T1RrMU9EQTVJaXdpTnpZNU1UY3pOREl6TURjMU16RXhPVFV5TVNJc0lqYzJPVEExTlRVNE1EUXhNemcyTnpFek9UTWlMQ0kzTmpnNU5UQXhORGN4T1RVeE16YzFOakk1SWl3aU56WTVNRGsyTXpFME1ESTVOalkxT0RJd09TSXNJamMyT0RrNE16TXhNREUwTnpFMU16UXpOamdpTENJM05qZzVNek14T0RFeE16TXhNVFE1TURjNElpd2lOelk1TURFMk9EUTBPREV4TkRBMk9EYzBNeUlzSWpjMk9EazFPRFU0TkRBeE5qSXpOakExT0RRaUxDSTNOamc1T0RneU5UYzVPVEF4TnpZeU9ETXdJaXdpTnpZNE9UY3pORGt4TXpFME5qTTNOVFEwTWlJc0lqYzJPVEV3T1RrMk1UZ3pOemN3TkRNeU1qRWlMQ0kzTmpnNU1qQTROakUwTnpZMk1USXdNakV6SWl3aU56WTVNVFkzT0Rrek5EUXdPREUzTURjMk5TSXNJamMyT0Rrek5qZzJORFF3TnpNeE5qUXdOVE1pTENJM05qa3hPRFEyTmpFM01qQTROVEkwTURRMUlpd2lOelk1TVRRNE5qSTVOVEF6TnpZMk1EUXpOeUlzSWpjMk9URXhPRGcyTVRNNU5UUXdNekE0T0RBaUxDSTNOamt4TWpnMk1EVXhNalV4TXpVNE9UazJJaXdpTnpZNE9EVXpOVE13TmpreE5UVTVOelU0TWlJc0lqYzJPVEF4TVRNM056VXpOalUyTnpJeE9UTWlMQ0kzTmpJME1qUTVPRFV4TVRnMU56UTFNVGcxSWl3aU56WTVNVGN6TmpjNU1ETXdNakkwT0RFNU15SXNJamMyT0RjNE5ERXdOekUyTnpNME1qa3lOemtpTENJM05qa3hPRFF6TnpnME9UVTROVGswTXpJMUlpd2lOelk0T1RRNE5ETTBNVEU1TXpJNE1EZ3dNU0pkZlEifQ", "total": null, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pYUNJc0ltTWlPaUp6WXpFdVpYbEtha2xxYjJsTmVrRnBURU5LZWtscWNHSkphbU15VDBSSk1FNUVZekpOZWxWNFRtcG5NRTVFWXpOT2VsbHBURU5KTTA1cVp6Sk9SRkV5VGxSRk1rMUVaelJPYWxVeFRWUkpNa2xwZDJsT2VsazFUVlJOTTA1RVNUTk9ha0V6VFVSUk1FNUVUWGROVTBselNXcGpNazlVUlRCTlJGa3hUVlJuTkU1RVNUVk5ha0Y1VFdwTmFVeERTVE5PYW10NFRYcEJOVTVVWnpKT1ZFRjRUMVJyTVU5RVFUVkphWGRwVG5wWk5VMVVZM3BPUkVsNlRVUmpNVTE2UlhoUFZGVjVUVk5KYzBscVl6SlBWRUV4VGxSVk5FMUVVWGhOZW1jeVRucEZlazlVVFdsTVEwa3pUbXBuTlU1VVFYaE9SR040VDFSVmVFMTZZekZPYWtrMVNXbDNhVTU2V1RWTlJHc3lUWHBGTUUxRVNUVk9hbGt4VDBSSmQwOVRTWE5KYW1NeVQwUnJORTE2VFhoTlJFVXdUbnBGTVUxNlVYcE9hbWRwVEVOSk0wNXFaelZOZWsxNFQwUkZlRTE2VFhoTlZGRTFUVVJqTkVscGQybE9lbGsxVFVSRk1rOUVVVEJQUkVWNFRrUkJNazlFWXpCTmVVbHpTV3BqTWs5RWF6RlBSRlUwVGtSQmVFNXFTWHBPYWtFeFQwUlJhVXhEU1ROT2FtYzFUMFJuZVU1VVl6VlBWRUY0VG5wWmVVOUVUWGRKYVhkcFRucFpORTlVWTNwT1JHdDRUWHBGTUU1cVRUTk9WRkV3VFdsSmMwbHFZekpQVkVWM1QxUnJNazFVWjNwT2VtTjNUa1JOZVUxcVJXbE1RMGt6VG1wbk5VMXFRVFJPYWtVd1RucFpNazFVU1hkTmFrVjZTV2wzYVU1NldUVk5WRmt6VDBScmVrNUVVWGRQUkVVelRVUmpNazVUU1hOSmFtTXlUMFJyZWs1cVp6Sk9SRkYzVG5wTmVFNXFVWGRPVkUxcFRFTkpNMDVxYTNoUFJGRXlUbXBGTTAxcVFUUk9WRWt3VFVSUk1VbHBkMmxPZWxrMVRWUlJORTVxU1RWT1ZFRjZUbnBaTWsxRVVYcE9lVWx6U1dwak1rOVVSWGhQUkdjeVRWUk5OVTVVVVhkTmVrRTBUMFJCYVV4RFNUTk9hbXQ0VFdwbk1rMUVWWGhOYWxWNFRYcFZORTlVYXpKSmFYZHBUbnBaTkU5RVZYcE9WRTEzVG1wcmVFNVVWVFZPZWxVMFRXbEpjMGxxWXpKUFZFRjRUVlJOTTA1NlZYcE9hbFV5VG5wSmVFOVVUV2xNUTBrelRtcEpNRTFxVVRWUFJGVjRUVlJuTVU1NlVURk5WR2N4U1dsM2FVNTZXVFZOVkdONlRtcGpOVTFFVFhkTmFra3dUMFJGTlUxNVNYTkphbU15VDBSak5FNUVSWGRPZWtVeVRucE5NRTFxYTNsT2VtdHBURU5KTTA1cWEzaFBSRkY2VG5wbk1FOVVWVFJPVkdzd1RYcEpNVWxwZDJsT2VsazBUMVJSTkU1RVRUQk5WRVUxVFhwSk5FMUVaM2ROVTBwa1psRWlmUSIsImUiOiJ0aWt0b2svc2VhcmNoL3RvcCIsInAiOiJjdXJzb3IifQ", "has_more": true, "page_size": 30 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T07:27:23.464Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/search/users": { "get": { "summary": "Search TikTok users", "description": "Searches TikTok for user accounts matching a query, 30 per page. Each row carries the username, display name, avatar, profile URL, verification status, whether the account is private, and the follower, following, video and like counts. The search surface publishes nothing else, so on a plain call `author.bio`, `author.location`, `author.ext.bio_link` and `author.ext.business_category` are null on every row. Send `include=profile` and every row is joined, in the same call, to the profile lookup that carries them: the bio, the ISO 3166-1 alpha-2 region at `author.location`, the link in the bio and the account category land on each row. Cost: 1 credit for the page plus 1 credit per row filled from a fresh lookup (30 rows, so 31 at most); rows already in cache are filled for free, rows that could not be filled are refunded, and a repeat of the same call within the cache window is 0. Time: a plain call is about 2 seconds; `include=profile` adds 4 to 9 seconds on a fresh page (the lookups run in parallel and the call waits for the slowest, never more than 12 seconds) and nothing when the rows are already cached. `limit=N` (1 to 30) takes the top N rows of the page and, with `include`, caps the extra credits at N. The response carries a `hydration` block itemising rows, lookups, cache hits, credits and milliseconds. The counts on a search row are the search index's own figures and can trail the profile's by a few thousand on a large account; the join never overwrites a value the row already carries. Page with cursor. Send `country=` as an ISO 3166-1 alpha-2 code (KR, US, DE, …) to search for creators whose account region is that country instead of the global page: each returned row already carries `author.location`, the bio and the profile URL, the call does not paginate, and a row whose region does not match is dropped. A row is also dropped when neither its matched video, bio nor name is about your query, so a query that names only a market or a kind of account (\"influencers\") returns an empty page at 0 credits; put the topic in `query`. Cost: 5 credits per in-country creator returned (8 by default, at most 20 via `limit`); unused slots are refunded. A typo is a free 400. The global 1-credit page is unchanged when `country` is omitted.", "tags": [ "tiktok" ], "operationId": "get_tiktok_search_users", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 100, "x-credit-cost-formula": "1 credit for the page. include=profile holds 1 credit per row, at most 30 (or `limit`), and keeps only the rows filled from a fresh lookup, so a page is at most 31 credits; rows served from cache are free, unfilled rows are refunded, and a repeat within the cache window costs 0. country= holds 5 credits per requested in-country row (8 by default, at most 20) and keeps only the rows returned, so a miss is 0. The page is cached for 2 minutes and the per-account lookups for 15 minutes. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total.", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search keyword or phrase to find TikTok users", "schema": { "type": "string" }, "example": "cooking" }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor to get more users. Get 'cursor' from previous response.", "schema": { "type": "integer" } }, { "name": "trim", "in": "query", "required": false, "description": "Accepted for compatibility; the response is already the canonical shape, so this flag has no effect.", "schema": { "type": "boolean" } }, { "name": "include", "in": "query", "required": false, "description": "Set to `profile` (one token only) to fill `author.bio`, `author.location` (the ISO region), `author.ext.bio_link` and `author.ext.business_category` on every row in this one call. Holds 1 credit per row (at most 30, or `limit`) and keeps only the rows filled from a fresh lookup; rows already in cache and rows that could not be filled are refunded, so the most a call can cost is 1 + rows. Adds 4 to 9 seconds on a fresh page (never more than 12) and nothing when the rows are already cached; read `data.hydration` for the rows, the credits held and kept, and the time.", "schema": { "type": "string", "enum": [ "profile" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Take the top N rows of the page (1 to 30) after the search has run. With `include=profile` it also caps the extra credits at N: `limit=5&include=profile` costs at most 6. With `country=` it is the in-country page size (1 to 20, default 8) and the credit cap at 5 per row. On the global page it is not a page size: `next_cursor` still advances past the full page, so rows beyond N on this page are not returned by the next page.", "schema": { "type": "integer", "minimum": 1, "maximum": 30 } }, { "name": "country", "in": "query", "required": false, "description": "ISO 3166-1 alpha-2 account region to filter by (KR, US, DE, …). Returns only creators whose public region is that country, 5 credits per row returned (8 by default, at most 20). A row is also dropped when neither its matched video, bio nor name is about your query, so a query that names only a market or a kind of account (\"influencers\") returns an empty page at 0 credits; put the topic in `query`. Omit it for the global 1-credit page. A code this endpoint does not accept is a free 400.", "schema": { "type": "string", "enum": [ "US", "GB", "CA", "AU", "NZ", "IE", "DE", "FR", "ES", "IT", "PT", "NL", "BE", "CH", "AT", "SE", "NO", "DK", "FI", "IS", "PL", "CZ", "SK", "HU", "RO", "BG", "GR", "HR", "RS", "SI", "UA", "RU", "TR", "IL", "AE", "SA", "QA", "KW", "EG", "MA", "ZA", "NG", "KE", "GH", "TZ", "ET", "BR", "MX", "AR", "CO", "CL", "PE", "VE", "EC", "UY", "PY", "BO", "CR", "PA", "DO", "JM", "JP", "KR", "CN", "TW", "HK", "MO", "SG", "MY", "ID", "TH", "VN", "PH", "IN", "PK", "BD", "LK", "NP", "MM", "KH" ] }, "example": "KR" }, { "name": "max_pages", "in": "query", "required": false, "description": "1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "max_items", "in": "query", "required": false, "description": "1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: \"max_items\"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`\"time_budget\"`): send the returned cursor with the same params to continue.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "max_credits", "in": "query", "required": false, "description": "1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: \"max_credits\"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/search/users" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical author wrappers ({ author })", "items": { "type": "object", "description": "Canonical author wrapper", "properties": { "author": { "type": "object", "description": "Canonical Author object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)" }, "username": { "type": [ "string", "null" ], "description": "User handle or username" }, "display_name": { "type": [ "string", "null" ], "description": "Display name or full name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to profile picture" }, "bio": { "type": [ "string", "null" ], "description": "Profile biography or description" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the account is verified" }, "followers": { "type": [ "integer", "null" ], "description": "Follower or subscriber count as an integer. Exact on Instagram and on TikTok when the source exposes an unrounded figure. YouTube above 1,000 subscribers is YouTube's published three-significant-figure figure. When the integer is a published/rounded value, `author.ext.followers_approximate` is true." }, "following": { "type": [ "integer", "null" ], "description": "Number of accounts followed" }, "posts_count": { "type": [ "integer", "null" ], "description": "Total number of posts / videos / tracks / episodes" }, "likes_count": { "type": [ "integer", "null" ], "description": "Total likes received across the author's content (when surfaced)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the profile page" }, "location": { "type": [ "string", "null" ], "description": "ISO region code (e.g. `US`) or freeform location string when surfaced" }, "external_url": { "type": [ "string", "null" ], "description": "Bio link / external website URL when surfaced by the platform" }, "private": { "type": [ "boolean", "null" ], "description": "Boolean at author.private" }, "joined_at": { "type": [ "string", "null" ], "description": "String at author.joined_at" }, "last_post_at": { "type": [ "string", "null" ], "description": "String at author.last_post_at" }, "ext": { "type": [ "object", "null" ], "description": "Nested object: author.ext", "properties": { "social_context": { "type": [ "string", "null" ], "description": "String at author.ext.social_context" }, "account_created": { "type": [ "string", "null" ], "description": "String at author.ext.account_created" }, "country": { "type": [ "string", "null" ], "description": "String at author.ext.country" }, "country_name": { "type": [ "string", "null" ], "description": "String at author.ext.country_name" }, "collects_received": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.collects_received" }, "former_usernames": { "type": [ "array", "null" ], "description": "Array at author.ext.former_usernames", "items": { "type": "string", "description": "String at author.ext.former_usernames" } }, "former_usernames_count": { "type": [ "integer", "null" ], "description": "Instagram profile/about: how many former usernames Instagram's \"About this account\" panel lists for the account. 0 when the panel lists none, null when the panel could not be read on this call (the response then carries a note saying so). A count above 0 means the handle was renamed at least once; the names themselves are not published." }, "verified_at": { "type": [ "string", "null" ], "description": "Instagram profile/about, opt-in (`include=verified_at`): the month Instagram verified the account, as the panel shows it (\"April 2024\"). A month, not a date. Null when the account is not verified or the panel shows no verification date. Absent unless requested." }, "public_email": { "type": [ "string", "null" ], "description": "String at author.ext.public_email" }, "contact_email": { "type": [ "string", "null" ], "description": "Opt-in (`contact_email=1` on instagram/profile, youtube/channel and youtube/channel/about). When the bio lists two or more email addresses, the one the creator gives for contacting them personally, copied verbatim. Null when there is one address or none, when every address belongs to a manager, agency or brand, or when the choice was not confident. `author.ext.public_email` (the first address in the bio) is unchanged." }, "public_phone": { "type": [ "string", "null" ], "description": "String at author.ext.public_phone" }, "similar_source": { "type": [ "string", "null" ], "description": "String at author.ext.similar_source" }, "instagram_username": { "type": [ "string", "null" ], "description": "String at author.ext.instagram_username" }, "similar_via": { "type": [ "string", "null" ], "description": "String at author.ext.similar_via" }, "business_category": { "type": [ "string", "null" ], "description": "String at author.ext.business_category" }, "bio_links": { "type": [ "array", "null" ], "description": "Array at author.ext.bio_links", "items": { "type": "object", "description": "Nested object: author.ext.bio_links", "properties": { "title": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.title" }, "url": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.url" }, "link_type": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.link_type" } } } }, "is_business": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_business" }, "is_professional": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_professional" }, "creator_marketplace": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.creator_marketplace" }, "verification_label": { "type": [ "string", "null" ], "description": "String at author.ext.verification_label" }, "fbid": { "type": [ "string", "null" ], "description": "String at author.ext.fbid" }, "hd_avatar_url": { "type": [ "string", "null" ], "description": "String at author.ext.hd_avatar_url" }, "website": { "type": [ "string", "null" ], "description": "String at author.ext.website" }, "cover_url": { "type": [ "string", "null" ], "description": "String at author.ext.cover_url" }, "page_active": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.page_active" }, "employee_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.employee_count" }, "employee_count_range": { "type": [ "object", "null" ], "description": "Nested object: author.ext.employee_count_range", "properties": { "start": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.employee_count_range.start" }, "end": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.employee_count_range.end" } } }, "founded_year": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.founded_year" }, "company_type": { "type": [ "string", "null" ], "description": "String at author.ext.company_type" }, "tagline": { "type": [ "string", "null" ], "description": "String at author.ext.tagline" }, "specialities": { "type": [ "array", "null" ], "description": "Array at author.ext.specialities", "items": { "type": "string", "description": "String at author.ext.specialities" } }, "industries": { "type": [ "array", "null" ], "description": "Array at author.ext.industries", "items": { "type": "string", "description": "String at author.ext.industries" } }, "headquarters": { "type": [ "string", "null" ], "description": "Leaf at author.ext.headquarters" }, "locations": { "type": [ "array", "null" ], "description": "Array at author.ext.locations", "items": { "type": "string", "description": "Leaf at author.ext.locations" } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at author.ext.hashtags", "items": { "type": "string", "description": "Leaf at author.ext.hashtags" } }, "funding": { "type": [ "string", "null" ], "description": "Leaf at author.ext.funding" }, "address": { "type": [ "string", "null" ], "description": "String at author.ext.address" }, "price_range": { "type": [ "string", "null" ], "description": "String at author.ext.price_range" }, "rating": { "type": [ "string", "null" ], "description": "String at author.ext.rating" }, "rating_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.rating_count" }, "talking_about_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.talking_about_count" }, "business_hours": { "type": [ "array", "null" ], "description": "Array at author.ext.business_hours", "items": { "type": "string", "description": "Leaf at author.ext.business_hours" } }, "links": { "type": [ "array", "null" ], "description": "Array at author.ext.links", "items": { "type": "string", "description": "Leaf at author.ext.links" } }, "ad_library_page_id": { "type": [ "string", "null" ], "description": "String at author.ext.ad_library_page_id" }, "ad_library_status": { "type": [ "string", "null" ], "description": "String at author.ext.ad_library_status" }, "urn": { "type": [ "string", "null" ], "description": "String at author.ext.urn" }, "is_top_voice": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_top_voice" }, "is_premium": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_premium" }, "is_creator": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_creator" }, "is_influencer": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_influencer" }, "is_open_to_work": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_open_to_work" }, "is_hiring": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_hiring" }, "member_id": { "type": [ "string", "null" ], "description": "String at author.ext.member_id" }, "company_id": { "type": [ "string", "null" ], "description": "String at author.ext.company_id" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at author.ext.reaction_type" }, "followers_approximate": { "type": [ "boolean", "null" ], "description": "True when `author.followers` is a published or rounded figure rather than an unrounded census: LinkedIn people-list display buckets, TikTok `stats.followerCount` when the exact sibling is absent, and YouTube subscriber counts at or above 1,000. Null or absent on exact counts." }, "counts_source": { "type": [ "string", "null" ], "description": "TikTok profile only. Which of TikTok's two live counter sets `author.followers`, `author.following`, `author.likes_count` and `author.posts_count` carry: `app` (TikTok's app counters, the default) or `web` (the website's `statsV2`, returned with `counts=web`). The two sets can differ by a few percent in either direction." }, "keywords": { "type": [ "string", "null" ], "description": "String at author.ext.keywords" }, "total_views": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.total_views" }, "joined_at_timestamp": { "type": [ "string", "null" ], "description": "String at author.ext.joined_at_timestamp" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at author.ext.topicCategories", "items": { "type": "string", "description": "String at author.ext.topicCategories" } }, "bannerExternalUrl": { "type": [ "string", "null" ], "description": "String at author.ext.bannerExternalUrl" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.madeForKids" }, "hiddenSubscriberCount": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.hiddenSubscriberCount" }, "related_playlists": { "type": [ "string", "null" ], "description": "Leaf at author.ext.related_playlists" }, "topic_ids": { "type": [ "array", "null" ], "description": "Array at author.ext.topic_ids", "items": { "type": "string", "description": "String at author.ext.topic_ids" } }, "unsubscribed_trailer": { "type": [ "string", "null" ], "description": "String at author.ext.unsubscribed_trailer" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at author.ext.localizations" }, "monthly_listeners": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.monthly_listeners" }, "total_ratings": { "type": [ "integer", "null" ], "description": "Spotify podcasts only: how many listeners have rated the show. Cumulative over the show's whole run, so it reflects longevity as well as size, and it is NOT an audience count (Spotify publishes no play, download, subscriber or follower count for a podcast)" }, "average_rating": { "type": [ "integer", "null" ], "description": "Spotify podcasts only: mean listener rating from 0 to 5. Fractional (e.g. 4.66) despite the integer type this schema emits for every numeric leaf" }, "creator_username": { "type": [ "string", "null" ], "description": "String at author.ext.creator_username" }, "join_policy": { "type": [ "string", "null" ], "description": "String at author.ext.join_policy" }, "is_nsfw": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_nsfw" }, "rules": { "type": [ "array", "null" ], "description": "Array at author.ext.rules", "items": { "type": "string", "description": "Leaf at author.ext.rules" } }, "weekly_active_users": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.weekly_active_users" }, "weekly_contributions": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.weekly_contributions" }, "rules_text": { "type": [ "string", "null" ], "description": "String at author.ext.rules_text" }, "language": { "type": [ "string", "null" ], "description": "String at author.ext.language" }, "post_karma": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.post_karma" }, "comment_karma": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.comment_karma" }, "awardee_karma": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.awardee_karma" }, "trophy_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.trophy_count" }, "banner_url": { "type": [ "string", "null" ], "description": "String at author.ext.banner_url" }, "profile_title": { "type": [ "string", "null" ], "description": "String at author.ext.profile_title" }, "social_links": { "type": [ "array", "null" ], "description": "Array at author.ext.social_links", "items": { "type": "string", "description": "Leaf at author.ext.social_links" } }, "bio_link": { "type": [ "string", "null" ], "description": "String at author.ext.bio_link" }, "embed_html": { "type": [ "string", "null" ], "description": "String at author.ext.embed_html" }, "embed_url": { "type": [ "string", "null" ], "description": "String at author.ext.embed_url" }, "group": { "type": [ "string", "null" ], "description": "Leaf at author.ext.group" }, "search_hit": { "type": [ "object", "null" ], "description": "Nested object: author.ext.search_hit", "properties": { "match": { "type": [ "string", "null" ], "description": "Leaf at author.ext.search_hit.match" }, "title": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.title" }, "snippet": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.snippet" }, "evidence_url": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.evidence_url" }, "matched_urls": { "type": [ "array", "null" ], "description": "Array at author.ext.search_hit.matched_urls", "items": { "type": "string", "description": "String at author.ext.search_hit.matched_urls" } } } }, "blog_name": { "type": [ "string", "null" ], "description": "String at author.ext.blog_name" }, "blog_no": { "type": [ "string", "null" ], "description": "String at author.ext.blog_no" }, "visitors_today": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.visitors_today" }, "visitors_total": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.visitors_total" }, "topic": { "type": [ "string", "null" ], "description": "String at author.ext.topic" }, "power_blog": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.power_blog" }, "official_blog": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.official_blog" } } } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/search/users", "data": { "items": [ { "author": { "id": "user_b74616", "username": "user_ef0400", "display_name": "user_82bd81", "avatar_url": "https://example.com/avatars/user_821deb.png", "bio": null, "verified": false, "followers": 14408, "following": 219, "posts_count": 262, "likes_count": 74311, "url": "https://example.com/user_46a6c2", "location": null, "private": false } }, { "author": { "id": "user_709cf2", "username": "user_c06917", "display_name": "user_e5d123", "avatar_url": "https://example.com/avatars/user_c98d93.png", "bio": null, "verified": true, "followers": 4989481, "following": 42, "posts_count": 673, "likes_count": 113375507, "url": "https://example.com/user_454f83", "location": null, "private": false } } ], "next_cursor": "sc2.eyJzIjoiYiIsImMiOiJzY3AuZXlKMklqb3hMQ0p4SWpwN0ltTjFjbk52Y2lJNklqTXdJaXdpYzJWaGNtTm9YMmxrSWpvaU1qQXlOakV3TURJd056STNNalEzUWpRek0wVkVOMFZDTjBJMU1FTkNNMFkyUmlKOWZRIn0", "total": null, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWWlJc0ltTWlPaUp6WTNBdVpYbEtNa2xxYjNoTVEwcDRTV3B3TjBsdFRqRmpiazUyWTJsSk5rbHFUWGRKYVhkcFl6SldhR050VG05WU1teHJTV3B2YVUxcVFYbE9ha1YzVFVSSmQwNTZTVE5OYWxFelVXcFJlazB3VmtWT01GWkRUakJKTVUxRlRrTk5NRmt5VW1sS09XWlJJbjAiLCJlIjoidGlrdG9rL3NlYXJjaC91c2VycyIsInAiOiJjdXJzb3IifQ", "has_more": true, "page_size": 2 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T07:27:26.112Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/similar": { "get": { "summary": "List similar TikTok accounts", "description": "Returns TikTok accounts similar to a given creator: the related accounts TikTok itself suggests for that profile, usually about 30. Some creators get only a few, and for some TikTok suggests none. Each account includes the username, display name, avatar, profile URL, bio, verification status, whether it is private, and its follower, following, video and like counts, so no second lookup is needed to size or qualify a lookalike. Pass `handle`. The list is specific to the seed: a chef returns other chefs and food creators, a dancer returns other dancers. To go wider, call it again with any returned username as the next `handle`. When TikTok has no list for the creator, the list is built from TikTok's lists that include the creator: the accounts whose list names the creator, then the other accounts on those lists, ranked by how many of those lists they appear on. Those rows carry `author.ext.similar_source` set to `tiktok_graph` and `author.ext.similar_via`, the account whose list named the creator. Any remaining places are filled from the accounts Instagram suggests for the same creator, matched to their TikTok accounts and kept only when the TikTok account is verified, has at least 10,000 followers, or has at least 1,000 followers and a display name that shares a word with the Instagram account; the creator's Instagram account is the one linked or named in the TikTok bio when there is one. Those rows carry `author.ext.similar_source` set to `instagram` and `author.ext.instagram_username`. TikTok's own rows carry neither. Cost: 5 credits a call. A creator with no suggestions returns an empty list and is refunded, and a handle TikTok does not know is a 404 at no cost. A repeat within the cache window is 0 credits. The list is a single fixed window: it is not paginated and returns no cursor. author.location is not published on this surface and is null on every row; `GET /v1/tiktok/profile` returns the region for any single account.", "tags": [ "tiktok" ], "operationId": "get_tiktok_similar", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "x-credit-cost-formula": "5 credits a call. An empty list is refunded, an unknown handle is a free 404, and the list is cached for 15 minutes, so a repeat within that window costs 0.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "TikTok username of the seed creator, without the @ symbol.", "schema": { "type": "string" }, "example": "gordonramsayofficial" }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/similar" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical author wrappers ({ author })", "items": { "type": "object", "description": "Canonical author wrapper", "properties": { "author": { "type": "object", "description": "Canonical Author object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)" }, "username": { "type": [ "string", "null" ], "description": "User handle or username" }, "display_name": { "type": [ "string", "null" ], "description": "Display name or full name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to profile picture" }, "bio": { "type": [ "string", "null" ], "description": "Profile biography or description" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the account is verified" }, "followers": { "type": [ "integer", "null" ], "description": "Follower or subscriber count as an integer. Exact on Instagram and on TikTok when the source exposes an unrounded figure. YouTube above 1,000 subscribers is YouTube's published three-significant-figure figure. When the integer is a published/rounded value, `author.ext.followers_approximate` is true." }, "following": { "type": [ "integer", "null" ], "description": "Number of accounts followed" }, "posts_count": { "type": [ "integer", "null" ], "description": "Total number of posts / videos / tracks / episodes" }, "likes_count": { "type": [ "integer", "null" ], "description": "Total likes received across the author's content (when surfaced)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the profile page" }, "location": { "type": [ "string", "null" ], "description": "ISO region code (e.g. `US`) or freeform location string when surfaced" }, "external_url": { "type": [ "string", "null" ], "description": "Bio link / external website URL when surfaced by the platform" }, "private": { "type": [ "boolean", "null" ], "description": "Boolean at author.private" }, "joined_at": { "type": [ "string", "null" ], "description": "String at author.joined_at" }, "last_post_at": { "type": [ "string", "null" ], "description": "String at author.last_post_at" }, "ext": { "type": [ "object", "null" ], "description": "Nested object: author.ext", "properties": { "social_context": { "type": [ "string", "null" ], "description": "String at author.ext.social_context" }, "account_created": { "type": [ "string", "null" ], "description": "String at author.ext.account_created" }, "country": { "type": [ "string", "null" ], "description": "String at author.ext.country" }, "country_name": { "type": [ "string", "null" ], "description": "String at author.ext.country_name" }, "collects_received": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.collects_received" }, "former_usernames": { "type": [ "array", "null" ], "description": "Array at author.ext.former_usernames", "items": { "type": "string", "description": "String at author.ext.former_usernames" } }, "former_usernames_count": { "type": [ "integer", "null" ], "description": "Instagram profile/about: how many former usernames Instagram's \"About this account\" panel lists for the account. 0 when the panel lists none, null when the panel could not be read on this call (the response then carries a note saying so). A count above 0 means the handle was renamed at least once; the names themselves are not published." }, "verified_at": { "type": [ "string", "null" ], "description": "Instagram profile/about, opt-in (`include=verified_at`): the month Instagram verified the account, as the panel shows it (\"April 2024\"). A month, not a date. Null when the account is not verified or the panel shows no verification date. Absent unless requested." }, "public_email": { "type": [ "string", "null" ], "description": "String at author.ext.public_email" }, "contact_email": { "type": [ "string", "null" ], "description": "Opt-in (`contact_email=1` on instagram/profile, youtube/channel and youtube/channel/about). When the bio lists two or more email addresses, the one the creator gives for contacting them personally, copied verbatim. Null when there is one address or none, when every address belongs to a manager, agency or brand, or when the choice was not confident. `author.ext.public_email` (the first address in the bio) is unchanged." }, "public_phone": { "type": [ "string", "null" ], "description": "String at author.ext.public_phone" }, "similar_source": { "type": [ "string", "null" ], "description": "String at author.ext.similar_source" }, "instagram_username": { "type": [ "string", "null" ], "description": "String at author.ext.instagram_username" }, "similar_via": { "type": [ "string", "null" ], "description": "String at author.ext.similar_via" }, "business_category": { "type": [ "string", "null" ], "description": "String at author.ext.business_category" }, "bio_links": { "type": [ "array", "null" ], "description": "Array at author.ext.bio_links", "items": { "type": "object", "description": "Nested object: author.ext.bio_links", "properties": { "title": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.title" }, "url": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.url" }, "link_type": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.link_type" } } } }, "is_business": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_business" }, "is_professional": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_professional" }, "creator_marketplace": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.creator_marketplace" }, "verification_label": { "type": [ "string", "null" ], "description": "String at author.ext.verification_label" }, "fbid": { "type": [ "string", "null" ], "description": "String at author.ext.fbid" }, "hd_avatar_url": { "type": [ "string", "null" ], "description": "String at author.ext.hd_avatar_url" }, "website": { "type": [ "string", "null" ], "description": "String at author.ext.website" }, "cover_url": { "type": [ "string", "null" ], "description": "String at author.ext.cover_url" }, "page_active": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.page_active" }, "employee_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.employee_count" }, "employee_count_range": { "type": [ "object", "null" ], "description": "Nested object: author.ext.employee_count_range", "properties": { "start": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.employee_count_range.start" }, "end": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.employee_count_range.end" } } }, "founded_year": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.founded_year" }, "company_type": { "type": [ "string", "null" ], "description": "String at author.ext.company_type" }, "tagline": { "type": [ "string", "null" ], "description": "String at author.ext.tagline" }, "specialities": { "type": [ "array", "null" ], "description": "Array at author.ext.specialities", "items": { "type": "string", "description": "String at author.ext.specialities" } }, "industries": { "type": [ "array", "null" ], "description": "Array at author.ext.industries", "items": { "type": "string", "description": "String at author.ext.industries" } }, "headquarters": { "type": [ "string", "null" ], "description": "Leaf at author.ext.headquarters" }, "locations": { "type": [ "array", "null" ], "description": "Array at author.ext.locations", "items": { "type": "string", "description": "Leaf at author.ext.locations" } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at author.ext.hashtags", "items": { "type": "string", "description": "Leaf at author.ext.hashtags" } }, "funding": { "type": [ "string", "null" ], "description": "Leaf at author.ext.funding" }, "address": { "type": [ "string", "null" ], "description": "String at author.ext.address" }, "price_range": { "type": [ "string", "null" ], "description": "String at author.ext.price_range" }, "rating": { "type": [ "string", "null" ], "description": "String at author.ext.rating" }, "rating_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.rating_count" }, "talking_about_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.talking_about_count" }, "business_hours": { "type": [ "array", "null" ], "description": "Array at author.ext.business_hours", "items": { "type": "string", "description": "Leaf at author.ext.business_hours" } }, "links": { "type": [ "array", "null" ], "description": "Array at author.ext.links", "items": { "type": "string", "description": "Leaf at author.ext.links" } }, "ad_library_page_id": { "type": [ "string", "null" ], "description": "String at author.ext.ad_library_page_id" }, "ad_library_status": { "type": [ "string", "null" ], "description": "String at author.ext.ad_library_status" }, "urn": { "type": [ "string", "null" ], "description": "String at author.ext.urn" }, "is_top_voice": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_top_voice" }, "is_premium": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_premium" }, "is_creator": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_creator" }, "is_influencer": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_influencer" }, "is_open_to_work": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_open_to_work" }, "is_hiring": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_hiring" }, "member_id": { "type": [ "string", "null" ], "description": "String at author.ext.member_id" }, "company_id": { "type": [ "string", "null" ], "description": "String at author.ext.company_id" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at author.ext.reaction_type" }, "followers_approximate": { "type": [ "boolean", "null" ], "description": "True when `author.followers` is a published or rounded figure rather than an unrounded census: LinkedIn people-list display buckets, TikTok `stats.followerCount` when the exact sibling is absent, and YouTube subscriber counts at or above 1,000. Null or absent on exact counts." }, "counts_source": { "type": [ "string", "null" ], "description": "TikTok profile only. Which of TikTok's two live counter sets `author.followers`, `author.following`, `author.likes_count` and `author.posts_count` carry: `app` (TikTok's app counters, the default) or `web` (the website's `statsV2`, returned with `counts=web`). The two sets can differ by a few percent in either direction." }, "keywords": { "type": [ "string", "null" ], "description": "String at author.ext.keywords" }, "total_views": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.total_views" }, "joined_at_timestamp": { "type": [ "string", "null" ], "description": "String at author.ext.joined_at_timestamp" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at author.ext.topicCategories", "items": { "type": "string", "description": "String at author.ext.topicCategories" } }, "bannerExternalUrl": { "type": [ "string", "null" ], "description": "String at author.ext.bannerExternalUrl" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.madeForKids" }, "hiddenSubscriberCount": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.hiddenSubscriberCount" }, "related_playlists": { "type": [ "string", "null" ], "description": "Leaf at author.ext.related_playlists" }, "topic_ids": { "type": [ "array", "null" ], "description": "Array at author.ext.topic_ids", "items": { "type": "string", "description": "String at author.ext.topic_ids" } }, "unsubscribed_trailer": { "type": [ "string", "null" ], "description": "String at author.ext.unsubscribed_trailer" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at author.ext.localizations" }, "monthly_listeners": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.monthly_listeners" }, "total_ratings": { "type": [ "integer", "null" ], "description": "Spotify podcasts only: how many listeners have rated the show. Cumulative over the show's whole run, so it reflects longevity as well as size, and it is NOT an audience count (Spotify publishes no play, download, subscriber or follower count for a podcast)" }, "average_rating": { "type": [ "integer", "null" ], "description": "Spotify podcasts only: mean listener rating from 0 to 5. Fractional (e.g. 4.66) despite the integer type this schema emits for every numeric leaf" }, "creator_username": { "type": [ "string", "null" ], "description": "String at author.ext.creator_username" }, "join_policy": { "type": [ "string", "null" ], "description": "String at author.ext.join_policy" }, "is_nsfw": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_nsfw" }, "rules": { "type": [ "array", "null" ], "description": "Array at author.ext.rules", "items": { "type": "string", "description": "Leaf at author.ext.rules" } }, "weekly_active_users": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.weekly_active_users" }, "weekly_contributions": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.weekly_contributions" }, "rules_text": { "type": [ "string", "null" ], "description": "String at author.ext.rules_text" }, "language": { "type": [ "string", "null" ], "description": "String at author.ext.language" }, "post_karma": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.post_karma" }, "comment_karma": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.comment_karma" }, "awardee_karma": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.awardee_karma" }, "trophy_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.trophy_count" }, "banner_url": { "type": [ "string", "null" ], "description": "String at author.ext.banner_url" }, "profile_title": { "type": [ "string", "null" ], "description": "String at author.ext.profile_title" }, "social_links": { "type": [ "array", "null" ], "description": "Array at author.ext.social_links", "items": { "type": "string", "description": "Leaf at author.ext.social_links" } }, "bio_link": { "type": [ "string", "null" ], "description": "String at author.ext.bio_link" }, "embed_html": { "type": [ "string", "null" ], "description": "String at author.ext.embed_html" }, "embed_url": { "type": [ "string", "null" ], "description": "String at author.ext.embed_url" }, "group": { "type": [ "string", "null" ], "description": "Leaf at author.ext.group" }, "search_hit": { "type": [ "object", "null" ], "description": "Nested object: author.ext.search_hit", "properties": { "match": { "type": [ "string", "null" ], "description": "Leaf at author.ext.search_hit.match" }, "title": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.title" }, "snippet": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.snippet" }, "evidence_url": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.evidence_url" }, "matched_urls": { "type": [ "array", "null" ], "description": "Array at author.ext.search_hit.matched_urls", "items": { "type": "string", "description": "String at author.ext.search_hit.matched_urls" } } } }, "blog_name": { "type": [ "string", "null" ], "description": "String at author.ext.blog_name" }, "blog_no": { "type": [ "string", "null" ], "description": "String at author.ext.blog_no" }, "visitors_today": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.visitors_today" }, "visitors_total": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.visitors_total" }, "topic": { "type": [ "string", "null" ], "description": "String at author.ext.topic" }, "power_blog": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.power_blog" }, "official_blog": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.official_blog" } } } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/similar", "data": { "items": [ { "author": { "id": "user_22bcfe", "username": "user_c79ea8", "display_name": "user_c79ea8", "avatar_url": "https://example.com/redacted", "bio": "Sample comment text (redacted).", "verified": true, "followers": 9821286, "following": 107, "posts_count": 84, "likes_count": 126853380, "url": "https://example.com/redacted", "location": null, "private": false, "joined_at": "user_1c6089" } }, { "author": { "id": "user_9f0260", "username": "user_0e8a11", "display_name": "user_0e8a11", "avatar_url": "https://example.com/avatars/user_40946d.png", "bio": "Sample comment text (redacted).", "verified": false, "followers": 118014, "following": 91, "posts_count": 219, "likes_count": 9527615, "url": "https://example.com/user_7462d3", "location": null, "private": false, "joined_at": "user_a5c378" } } ], "total": 30, "dropped": 0 }, "credits_used": 5, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": null, "has_more": false, "page_size": 30 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T13:09:58.882Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/user/audience": { "get": { "summary": "Get TikTok user audience demographics", "description": "Returns audience geography for a TikTok creator: audienceLocations ranks the top countries in the creator's audience with sampled follower counts and percentage share. The ranking is built from a sample of the creator's public followers (typically a few hundred), not the full follower base, so treat the percentages as a concentration ranking rather than a census. When the creator has a public Shop marketplace card, the same response also carries audienceAges and audienceGenders (percentage share) and audienceStates (sampled US-state counts). Age and gender are absent when no marketplace card exists; the country ranking is still returned.", "tags": [ "tiktok" ], "operationId": "get_tiktok_user_audience", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "TikTok username without the @ symbol", "schema": { "type": "string" }, "example": "charlidamelio" }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/user/audience" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "audienceLocations": { "type": [ "array", "null" ], "description": "Geographic distribution of the creator's audience, ordered by size. Passthrough from the upstream provider; present for creators whose platform exposes audience geography.", "items": { "type": "object", "description": "One country bucket of the audience", "properties": { "country": { "type": "string", "description": "Country name" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code" }, "count": { "type": "integer", "description": "Number of audience members in this country" }, "percentage": { "type": "string", "description": "Share of the audience in this country, formatted as a percent string (e.g. \"22.67%\")" } } } }, "audienceAges": { "type": [ "array", "null" ], "description": "Age-band share of the creator's audience, when a Shop marketplace card exists. Absent otherwise. Values are percentages.", "items": { "type": "object", "description": "One age band", "properties": { "key": { "type": "string", "description": "Age band, e.g. 18-24" }, "percentage": { "type": "number", "description": "Share of the audience in this band" } } } }, "audienceGenders": { "type": [ "array", "null" ], "description": "Gender share of the creator's audience, when a Shop marketplace card exists. Absent otherwise. Values are percentages and may not sum to 100.", "items": { "type": "object", "description": "One gender bucket", "properties": { "key": { "type": "string", "description": "Gender key, e.g. female" }, "percentage": { "type": "number", "description": "Share of the audience in this bucket" } } } }, "audienceStates": { "type": [ "array", "null" ], "description": "Sampled US-state counts for the creator's audience, when a Shop marketplace card exists. This is not a country ranking; use audienceLocations for that.", "items": { "type": "object", "description": "One US state bucket", "properties": { "state": { "type": "string", "description": "US state name" }, "count": { "type": "integer", "description": "Sampled audience members in this state" } } } }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } } }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/user/audience", "data": { "audienceLocations": [ { "country": "Pakistan", "countryCode": "PK", "count": 167, "percentage": "12.87%" }, { "country": "United States", "countryCode": "US", "count": 124, "percentage": "9.55%" } ], "audienceAges": [ { "key": "18-24", "percentage": 50.17 }, { "key": "25-34", "percentage": 28.22 } ], "audienceGenders": [ { "key": "male", "percentage": 24.16 }, { "key": "female", "percentage": 72.46 } ], "audienceStates": [ { "state": "CALIFORNIA", "count": 103700 }, { "state": "TEXAS", "count": 91800 } ] }, "credits_used": 5, "request_id": "req_example000000", "cached": false, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T15:40:39.979Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/user/followers": { "get": { "summary": "List TikTok user followers", "description": "Returns a list of followers for a TikTok user. Each follower includes username, display name, avatar, and follower count.", "tags": [ "tiktok" ], "operationId": "get_tiktok_user_followers", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-socialcrawl-oneOf": [ [ "handle", "user_id" ] ], "parameters": [ { "name": "handle", "in": "query", "required": false, "description": "TikTok username without the @ symbol (one of: handle, user_id; at least one required)", "schema": { "type": "string" }, "example": "stoolpresidente" }, { "name": "user_id", "in": "query", "required": false, "description": "User id. Use this for faster response times. (one of: handle, user_id; at least one required)", "schema": { "type": "string" } }, { "name": "min_time", "in": "query", "required": false, "description": "Used to paginate. Get 'min_time' from previous response. Native upstream cursor param. Send the universal `cursor` instead: the API maps it to this name for you.", "deprecated": true, "schema": { "type": "integer" } }, { "name": "trim", "in": "query", "required": false, "description": "Accepted for compatibility; the response is already the canonical shape, so this flag has no effect.", "schema": { "type": "boolean" } }, { "name": "max_pages", "in": "query", "required": false, "description": "1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "max_items", "in": "query", "required": false, "description": "1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: \"max_items\"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`\"time_budget\"`): send the returned cursor with the same params to continue.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "max_credits", "in": "query", "required": false, "description": "1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: \"max_credits\"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "cursor", "in": "query", "required": false, "description": "Universal pagination cursor. Send `pagination.next_cursor` from the previous response back verbatim: the API maps it to this endpoint's native `min_time` (cursor style). You never construct, decode, or look up a cursor. Omit it for page 1.", "schema": { "type": "string" } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/user/followers" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical author wrappers ({ author })", "items": { "type": "object", "description": "Canonical author wrapper", "properties": { "author": { "type": "object", "description": "Canonical Author object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)" }, "username": { "type": [ "string", "null" ], "description": "User handle or username" }, "display_name": { "type": [ "string", "null" ], "description": "Display name or full name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to profile picture" }, "bio": { "type": [ "string", "null" ], "description": "Profile biography or description" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the account is verified" }, "followers": { "type": [ "integer", "null" ], "description": "Follower or subscriber count as an integer. Exact on Instagram and on TikTok when the source exposes an unrounded figure. YouTube above 1,000 subscribers is YouTube's published three-significant-figure figure. When the integer is a published/rounded value, `author.ext.followers_approximate` is true." }, "following": { "type": [ "integer", "null" ], "description": "Number of accounts followed" }, "posts_count": { "type": [ "integer", "null" ], "description": "Total number of posts / videos / tracks / episodes" }, "likes_count": { "type": [ "integer", "null" ], "description": "Total likes received across the author's content (when surfaced)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the profile page" }, "location": { "type": [ "string", "null" ], "description": "ISO region code (e.g. `US`) or freeform location string when surfaced" }, "external_url": { "type": [ "string", "null" ], "description": "Bio link / external website URL when surfaced by the platform" }, "private": { "type": [ "boolean", "null" ], "description": "Boolean at author.private" }, "joined_at": { "type": [ "string", "null" ], "description": "String at author.joined_at" }, "last_post_at": { "type": [ "string", "null" ], "description": "String at author.last_post_at" }, "ext": { "type": [ "object", "null" ], "description": "Nested object: author.ext", "properties": { "social_context": { "type": [ "string", "null" ], "description": "String at author.ext.social_context" }, "account_created": { "type": [ "string", "null" ], "description": "String at author.ext.account_created" }, "country": { "type": [ "string", "null" ], "description": "String at author.ext.country" }, "country_name": { "type": [ "string", "null" ], "description": "String at author.ext.country_name" }, "collects_received": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.collects_received" }, "former_usernames": { "type": [ "array", "null" ], "description": "Array at author.ext.former_usernames", "items": { "type": "string", "description": "String at author.ext.former_usernames" } }, "former_usernames_count": { "type": [ "integer", "null" ], "description": "Instagram profile/about: how many former usernames Instagram's \"About this account\" panel lists for the account. 0 when the panel lists none, null when the panel could not be read on this call (the response then carries a note saying so). A count above 0 means the handle was renamed at least once; the names themselves are not published." }, "verified_at": { "type": [ "string", "null" ], "description": "Instagram profile/about, opt-in (`include=verified_at`): the month Instagram verified the account, as the panel shows it (\"April 2024\"). A month, not a date. Null when the account is not verified or the panel shows no verification date. Absent unless requested." }, "public_email": { "type": [ "string", "null" ], "description": "String at author.ext.public_email" }, "contact_email": { "type": [ "string", "null" ], "description": "Opt-in (`contact_email=1` on instagram/profile, youtube/channel and youtube/channel/about). When the bio lists two or more email addresses, the one the creator gives for contacting them personally, copied verbatim. Null when there is one address or none, when every address belongs to a manager, agency or brand, or when the choice was not confident. `author.ext.public_email` (the first address in the bio) is unchanged." }, "public_phone": { "type": [ "string", "null" ], "description": "String at author.ext.public_phone" }, "similar_source": { "type": [ "string", "null" ], "description": "String at author.ext.similar_source" }, "instagram_username": { "type": [ "string", "null" ], "description": "String at author.ext.instagram_username" }, "similar_via": { "type": [ "string", "null" ], "description": "String at author.ext.similar_via" }, "business_category": { "type": [ "string", "null" ], "description": "String at author.ext.business_category" }, "bio_links": { "type": [ "array", "null" ], "description": "Array at author.ext.bio_links", "items": { "type": "object", "description": "Nested object: author.ext.bio_links", "properties": { "title": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.title" }, "url": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.url" }, "link_type": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.link_type" } } } }, "is_business": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_business" }, "is_professional": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_professional" }, "creator_marketplace": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.creator_marketplace" }, "verification_label": { "type": [ "string", "null" ], "description": "String at author.ext.verification_label" }, "fbid": { "type": [ "string", "null" ], "description": "String at author.ext.fbid" }, "hd_avatar_url": { "type": [ "string", "null" ], "description": "String at author.ext.hd_avatar_url" }, "website": { "type": [ "string", "null" ], "description": "String at author.ext.website" }, "cover_url": { "type": [ "string", "null" ], "description": "String at author.ext.cover_url" }, "page_active": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.page_active" }, "employee_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.employee_count" }, "employee_count_range": { "type": [ "object", "null" ], "description": "Nested object: author.ext.employee_count_range", "properties": { "start": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.employee_count_range.start" }, "end": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.employee_count_range.end" } } }, "founded_year": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.founded_year" }, "company_type": { "type": [ "string", "null" ], "description": "String at author.ext.company_type" }, "tagline": { "type": [ "string", "null" ], "description": "String at author.ext.tagline" }, "specialities": { "type": [ "array", "null" ], "description": "Array at author.ext.specialities", "items": { "type": "string", "description": "String at author.ext.specialities" } }, "industries": { "type": [ "array", "null" ], "description": "Array at author.ext.industries", "items": { "type": "string", "description": "String at author.ext.industries" } }, "headquarters": { "type": [ "string", "null" ], "description": "Leaf at author.ext.headquarters" }, "locations": { "type": [ "array", "null" ], "description": "Array at author.ext.locations", "items": { "type": "string", "description": "Leaf at author.ext.locations" } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at author.ext.hashtags", "items": { "type": "string", "description": "Leaf at author.ext.hashtags" } }, "funding": { "type": [ "string", "null" ], "description": "Leaf at author.ext.funding" }, "address": { "type": [ "string", "null" ], "description": "String at author.ext.address" }, "price_range": { "type": [ "string", "null" ], "description": "String at author.ext.price_range" }, "rating": { "type": [ "string", "null" ], "description": "String at author.ext.rating" }, "rating_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.rating_count" }, "talking_about_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.talking_about_count" }, "business_hours": { "type": [ "array", "null" ], "description": "Array at author.ext.business_hours", "items": { "type": "string", "description": "Leaf at author.ext.business_hours" } }, "links": { "type": [ "array", "null" ], "description": "Array at author.ext.links", "items": { "type": "string", "description": "Leaf at author.ext.links" } }, "ad_library_page_id": { "type": [ "string", "null" ], "description": "String at author.ext.ad_library_page_id" }, "ad_library_status": { "type": [ "string", "null" ], "description": "String at author.ext.ad_library_status" }, "urn": { "type": [ "string", "null" ], "description": "String at author.ext.urn" }, "is_top_voice": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_top_voice" }, "is_premium": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_premium" }, "is_creator": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_creator" }, "is_influencer": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_influencer" }, "is_open_to_work": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_open_to_work" }, "is_hiring": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_hiring" }, "member_id": { "type": [ "string", "null" ], "description": "String at author.ext.member_id" }, "company_id": { "type": [ "string", "null" ], "description": "String at author.ext.company_id" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at author.ext.reaction_type" }, "followers_approximate": { "type": [ "boolean", "null" ], "description": "True when `author.followers` is a published or rounded figure rather than an unrounded census: LinkedIn people-list display buckets, TikTok `stats.followerCount` when the exact sibling is absent, and YouTube subscriber counts at or above 1,000. Null or absent on exact counts." }, "counts_source": { "type": [ "string", "null" ], "description": "TikTok profile only. Which of TikTok's two live counter sets `author.followers`, `author.following`, `author.likes_count` and `author.posts_count` carry: `app` (TikTok's app counters, the default) or `web` (the website's `statsV2`, returned with `counts=web`). The two sets can differ by a few percent in either direction." }, "keywords": { "type": [ "string", "null" ], "description": "String at author.ext.keywords" }, "total_views": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.total_views" }, "joined_at_timestamp": { "type": [ "string", "null" ], "description": "String at author.ext.joined_at_timestamp" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at author.ext.topicCategories", "items": { "type": "string", "description": "String at author.ext.topicCategories" } }, "bannerExternalUrl": { "type": [ "string", "null" ], "description": "String at author.ext.bannerExternalUrl" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.madeForKids" }, "hiddenSubscriberCount": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.hiddenSubscriberCount" }, "related_playlists": { "type": [ "string", "null" ], "description": "Leaf at author.ext.related_playlists" }, "topic_ids": { "type": [ "array", "null" ], "description": "Array at author.ext.topic_ids", "items": { "type": "string", "description": "String at author.ext.topic_ids" } }, "unsubscribed_trailer": { "type": [ "string", "null" ], "description": "String at author.ext.unsubscribed_trailer" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at author.ext.localizations" }, "monthly_listeners": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.monthly_listeners" }, "total_ratings": { "type": [ "integer", "null" ], "description": "Spotify podcasts only: how many listeners have rated the show. Cumulative over the show's whole run, so it reflects longevity as well as size, and it is NOT an audience count (Spotify publishes no play, download, subscriber or follower count for a podcast)" }, "average_rating": { "type": [ "integer", "null" ], "description": "Spotify podcasts only: mean listener rating from 0 to 5. Fractional (e.g. 4.66) despite the integer type this schema emits for every numeric leaf" }, "creator_username": { "type": [ "string", "null" ], "description": "String at author.ext.creator_username" }, "join_policy": { "type": [ "string", "null" ], "description": "String at author.ext.join_policy" }, "is_nsfw": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_nsfw" }, "rules": { "type": [ "array", "null" ], "description": "Array at author.ext.rules", "items": { "type": "string", "description": "Leaf at author.ext.rules" } }, "weekly_active_users": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.weekly_active_users" }, "weekly_contributions": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.weekly_contributions" }, "rules_text": { "type": [ "string", "null" ], "description": "String at author.ext.rules_text" }, "language": { "type": [ "string", "null" ], "description": "String at author.ext.language" }, "post_karma": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.post_karma" }, "comment_karma": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.comment_karma" }, "awardee_karma": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.awardee_karma" }, "trophy_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.trophy_count" }, "banner_url": { "type": [ "string", "null" ], "description": "String at author.ext.banner_url" }, "profile_title": { "type": [ "string", "null" ], "description": "String at author.ext.profile_title" }, "social_links": { "type": [ "array", "null" ], "description": "Array at author.ext.social_links", "items": { "type": "string", "description": "Leaf at author.ext.social_links" } }, "bio_link": { "type": [ "string", "null" ], "description": "String at author.ext.bio_link" }, "embed_html": { "type": [ "string", "null" ], "description": "String at author.ext.embed_html" }, "embed_url": { "type": [ "string", "null" ], "description": "String at author.ext.embed_url" }, "group": { "type": [ "string", "null" ], "description": "Leaf at author.ext.group" }, "search_hit": { "type": [ "object", "null" ], "description": "Nested object: author.ext.search_hit", "properties": { "match": { "type": [ "string", "null" ], "description": "Leaf at author.ext.search_hit.match" }, "title": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.title" }, "snippet": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.snippet" }, "evidence_url": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.evidence_url" }, "matched_urls": { "type": [ "array", "null" ], "description": "Array at author.ext.search_hit.matched_urls", "items": { "type": "string", "description": "String at author.ext.search_hit.matched_urls" } } } }, "blog_name": { "type": [ "string", "null" ], "description": "String at author.ext.blog_name" }, "blog_no": { "type": [ "string", "null" ], "description": "String at author.ext.blog_no" }, "visitors_today": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.visitors_today" }, "visitors_total": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.visitors_total" }, "topic": { "type": [ "string", "null" ], "description": "String at author.ext.topic" }, "power_blog": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.power_blog" }, "official_blog": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.official_blog" } } } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/user/followers", "data": { "items": [ { "author": { "id": "user_24c8da", "username": "user_7e14d6", "display_name": "user_a1e547", "avatar_url": "https://example.com/avatars/user_a7c5c1.png", "bio": "Sample comment text (redacted).", "verified": false, "followers": 598, "following": 4137, "posts_count": 6, "likes_count": 394, "url": "https://example.com/user_9e37f6", "location": null, "private": false, "joined_at": "user_914ff9" } }, { "author": { "id": "user_b028ab", "username": "user_e684cc", "display_name": "user_8c5bda", "avatar_url": "https://example.com/avatars/user_d48bd1.png", "bio": "Sample comment text (redacted).", "verified": false, "followers": 4068, "following": 968, "posts_count": 77, "likes_count": 169236, "url": "https://example.com/user_bd389b", "location": null, "private": false, "joined_at": "user_b1c2eb" } } ], "next_cursor": "sc2.eyJzIjoiaCIsImMiOiIxNzkwOTAyODk5In0", "total": 4784231, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pYUNJc0ltTWlPaUl4Tnprd09UQXlPRGs1SW4wIiwiZSI6InRpa3Rvay91c2VyL2ZvbGxvd2VycyIsInAiOiJtaW5fdGltZSJ9", "has_more": true, "page_size": 150 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T13:11:34.617Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/user/following": { "get": { "summary": "List TikTok user following", "description": "Returns a list of accounts that a TikTok user is following. Each account includes username, display name, avatar, and follower count. Paginate with `min_time` from the previous response to walk the full list.", "tags": [ "tiktok" ], "operationId": "get_tiktok_user_following", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-socialcrawl-oneOf": [ [ "handle", "user_id" ] ], "parameters": [ { "name": "handle", "in": "query", "required": false, "description": "TikTok username without the @ symbol (one of: handle, user_id; at least one required)", "schema": { "type": "string" }, "example": "stoolpresidente" }, { "name": "user_id", "in": "query", "required": false, "description": "TikTok user id. Use this for faster responses. (one of: handle, user_id; at least one required)", "schema": { "type": "string" } }, { "name": "min_time", "in": "query", "required": false, "description": "Used to paginate. Get 'min_time' from previous response. Native upstream cursor param. Send the universal `cursor` instead: the API maps it to this name for you.", "deprecated": true, "schema": { "type": "integer" } }, { "name": "trim", "in": "query", "required": false, "description": "Accepted for compatibility; the response is already the canonical shape, so this flag has no effect.", "schema": { "type": "boolean" } }, { "name": "max_pages", "in": "query", "required": false, "description": "1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "max_items", "in": "query", "required": false, "description": "1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: \"max_items\"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`\"time_budget\"`): send the returned cursor with the same params to continue.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "max_credits", "in": "query", "required": false, "description": "1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: \"max_credits\"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "cursor", "in": "query", "required": false, "description": "Universal pagination cursor. Send `pagination.next_cursor` from the previous response back verbatim: the API maps it to this endpoint's native `min_time` (cursor style). You never construct, decode, or look up a cursor. Omit it for page 1.", "schema": { "type": "string" } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/user/following" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical author wrappers ({ author })", "items": { "type": "object", "description": "Canonical author wrapper", "properties": { "author": { "type": "object", "description": "Canonical Author object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)" }, "username": { "type": [ "string", "null" ], "description": "User handle or username" }, "display_name": { "type": [ "string", "null" ], "description": "Display name or full name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to profile picture" }, "bio": { "type": [ "string", "null" ], "description": "Profile biography or description" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the account is verified" }, "followers": { "type": [ "integer", "null" ], "description": "Follower or subscriber count as an integer. Exact on Instagram and on TikTok when the source exposes an unrounded figure. YouTube above 1,000 subscribers is YouTube's published three-significant-figure figure. When the integer is a published/rounded value, `author.ext.followers_approximate` is true." }, "following": { "type": [ "integer", "null" ], "description": "Number of accounts followed" }, "posts_count": { "type": [ "integer", "null" ], "description": "Total number of posts / videos / tracks / episodes" }, "likes_count": { "type": [ "integer", "null" ], "description": "Total likes received across the author's content (when surfaced)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the profile page" }, "location": { "type": [ "string", "null" ], "description": "ISO region code (e.g. `US`) or freeform location string when surfaced" }, "external_url": { "type": [ "string", "null" ], "description": "Bio link / external website URL when surfaced by the platform" }, "private": { "type": [ "boolean", "null" ], "description": "Boolean at author.private" }, "joined_at": { "type": [ "string", "null" ], "description": "String at author.joined_at" }, "last_post_at": { "type": [ "string", "null" ], "description": "String at author.last_post_at" }, "ext": { "type": [ "object", "null" ], "description": "Nested object: author.ext", "properties": { "social_context": { "type": [ "string", "null" ], "description": "String at author.ext.social_context" }, "account_created": { "type": [ "string", "null" ], "description": "String at author.ext.account_created" }, "country": { "type": [ "string", "null" ], "description": "String at author.ext.country" }, "country_name": { "type": [ "string", "null" ], "description": "String at author.ext.country_name" }, "collects_received": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.collects_received" }, "former_usernames": { "type": [ "array", "null" ], "description": "Array at author.ext.former_usernames", "items": { "type": "string", "description": "String at author.ext.former_usernames" } }, "former_usernames_count": { "type": [ "integer", "null" ], "description": "Instagram profile/about: how many former usernames Instagram's \"About this account\" panel lists for the account. 0 when the panel lists none, null when the panel could not be read on this call (the response then carries a note saying so). A count above 0 means the handle was renamed at least once; the names themselves are not published." }, "verified_at": { "type": [ "string", "null" ], "description": "Instagram profile/about, opt-in (`include=verified_at`): the month Instagram verified the account, as the panel shows it (\"April 2024\"). A month, not a date. Null when the account is not verified or the panel shows no verification date. Absent unless requested." }, "public_email": { "type": [ "string", "null" ], "description": "String at author.ext.public_email" }, "contact_email": { "type": [ "string", "null" ], "description": "Opt-in (`contact_email=1` on instagram/profile, youtube/channel and youtube/channel/about). When the bio lists two or more email addresses, the one the creator gives for contacting them personally, copied verbatim. Null when there is one address or none, when every address belongs to a manager, agency or brand, or when the choice was not confident. `author.ext.public_email` (the first address in the bio) is unchanged." }, "public_phone": { "type": [ "string", "null" ], "description": "String at author.ext.public_phone" }, "similar_source": { "type": [ "string", "null" ], "description": "String at author.ext.similar_source" }, "instagram_username": { "type": [ "string", "null" ], "description": "String at author.ext.instagram_username" }, "similar_via": { "type": [ "string", "null" ], "description": "String at author.ext.similar_via" }, "business_category": { "type": [ "string", "null" ], "description": "String at author.ext.business_category" }, "bio_links": { "type": [ "array", "null" ], "description": "Array at author.ext.bio_links", "items": { "type": "object", "description": "Nested object: author.ext.bio_links", "properties": { "title": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.title" }, "url": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.url" }, "link_type": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.link_type" } } } }, "is_business": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_business" }, "is_professional": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_professional" }, "creator_marketplace": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.creator_marketplace" }, "verification_label": { "type": [ "string", "null" ], "description": "String at author.ext.verification_label" }, "fbid": { "type": [ "string", "null" ], "description": "String at author.ext.fbid" }, "hd_avatar_url": { "type": [ "string", "null" ], "description": "String at author.ext.hd_avatar_url" }, "website": { "type": [ "string", "null" ], "description": "String at author.ext.website" }, "cover_url": { "type": [ "string", "null" ], "description": "String at author.ext.cover_url" }, "page_active": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.page_active" }, "employee_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.employee_count" }, "employee_count_range": { "type": [ "object", "null" ], "description": "Nested object: author.ext.employee_count_range", "properties": { "start": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.employee_count_range.start" }, "end": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.employee_count_range.end" } } }, "founded_year": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.founded_year" }, "company_type": { "type": [ "string", "null" ], "description": "String at author.ext.company_type" }, "tagline": { "type": [ "string", "null" ], "description": "String at author.ext.tagline" }, "specialities": { "type": [ "array", "null" ], "description": "Array at author.ext.specialities", "items": { "type": "string", "description": "String at author.ext.specialities" } }, "industries": { "type": [ "array", "null" ], "description": "Array at author.ext.industries", "items": { "type": "string", "description": "String at author.ext.industries" } }, "headquarters": { "type": [ "string", "null" ], "description": "Leaf at author.ext.headquarters" }, "locations": { "type": [ "array", "null" ], "description": "Array at author.ext.locations", "items": { "type": "string", "description": "Leaf at author.ext.locations" } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at author.ext.hashtags", "items": { "type": "string", "description": "Leaf at author.ext.hashtags" } }, "funding": { "type": [ "string", "null" ], "description": "Leaf at author.ext.funding" }, "address": { "type": [ "string", "null" ], "description": "String at author.ext.address" }, "price_range": { "type": [ "string", "null" ], "description": "String at author.ext.price_range" }, "rating": { "type": [ "string", "null" ], "description": "String at author.ext.rating" }, "rating_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.rating_count" }, "talking_about_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.talking_about_count" }, "business_hours": { "type": [ "array", "null" ], "description": "Array at author.ext.business_hours", "items": { "type": "string", "description": "Leaf at author.ext.business_hours" } }, "links": { "type": [ "array", "null" ], "description": "Array at author.ext.links", "items": { "type": "string", "description": "Leaf at author.ext.links" } }, "ad_library_page_id": { "type": [ "string", "null" ], "description": "String at author.ext.ad_library_page_id" }, "ad_library_status": { "type": [ "string", "null" ], "description": "String at author.ext.ad_library_status" }, "urn": { "type": [ "string", "null" ], "description": "String at author.ext.urn" }, "is_top_voice": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_top_voice" }, "is_premium": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_premium" }, "is_creator": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_creator" }, "is_influencer": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_influencer" }, "is_open_to_work": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_open_to_work" }, "is_hiring": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_hiring" }, "member_id": { "type": [ "string", "null" ], "description": "String at author.ext.member_id" }, "company_id": { "type": [ "string", "null" ], "description": "String at author.ext.company_id" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at author.ext.reaction_type" }, "followers_approximate": { "type": [ "boolean", "null" ], "description": "True when `author.followers` is a published or rounded figure rather than an unrounded census: LinkedIn people-list display buckets, TikTok `stats.followerCount` when the exact sibling is absent, and YouTube subscriber counts at or above 1,000. Null or absent on exact counts." }, "counts_source": { "type": [ "string", "null" ], "description": "TikTok profile only. Which of TikTok's two live counter sets `author.followers`, `author.following`, `author.likes_count` and `author.posts_count` carry: `app` (TikTok's app counters, the default) or `web` (the website's `statsV2`, returned with `counts=web`). The two sets can differ by a few percent in either direction." }, "keywords": { "type": [ "string", "null" ], "description": "String at author.ext.keywords" }, "total_views": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.total_views" }, "joined_at_timestamp": { "type": [ "string", "null" ], "description": "String at author.ext.joined_at_timestamp" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at author.ext.topicCategories", "items": { "type": "string", "description": "String at author.ext.topicCategories" } }, "bannerExternalUrl": { "type": [ "string", "null" ], "description": "String at author.ext.bannerExternalUrl" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.madeForKids" }, "hiddenSubscriberCount": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.hiddenSubscriberCount" }, "related_playlists": { "type": [ "string", "null" ], "description": "Leaf at author.ext.related_playlists" }, "topic_ids": { "type": [ "array", "null" ], "description": "Array at author.ext.topic_ids", "items": { "type": "string", "description": "String at author.ext.topic_ids" } }, "unsubscribed_trailer": { "type": [ "string", "null" ], "description": "String at author.ext.unsubscribed_trailer" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at author.ext.localizations" }, "monthly_listeners": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.monthly_listeners" }, "total_ratings": { "type": [ "integer", "null" ], "description": "Spotify podcasts only: how many listeners have rated the show. Cumulative over the show's whole run, so it reflects longevity as well as size, and it is NOT an audience count (Spotify publishes no play, download, subscriber or follower count for a podcast)" }, "average_rating": { "type": [ "integer", "null" ], "description": "Spotify podcasts only: mean listener rating from 0 to 5. Fractional (e.g. 4.66) despite the integer type this schema emits for every numeric leaf" }, "creator_username": { "type": [ "string", "null" ], "description": "String at author.ext.creator_username" }, "join_policy": { "type": [ "string", "null" ], "description": "String at author.ext.join_policy" }, "is_nsfw": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_nsfw" }, "rules": { "type": [ "array", "null" ], "description": "Array at author.ext.rules", "items": { "type": "string", "description": "Leaf at author.ext.rules" } }, "weekly_active_users": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.weekly_active_users" }, "weekly_contributions": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.weekly_contributions" }, "rules_text": { "type": [ "string", "null" ], "description": "String at author.ext.rules_text" }, "language": { "type": [ "string", "null" ], "description": "String at author.ext.language" }, "post_karma": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.post_karma" }, "comment_karma": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.comment_karma" }, "awardee_karma": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.awardee_karma" }, "trophy_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.trophy_count" }, "banner_url": { "type": [ "string", "null" ], "description": "String at author.ext.banner_url" }, "profile_title": { "type": [ "string", "null" ], "description": "String at author.ext.profile_title" }, "social_links": { "type": [ "array", "null" ], "description": "Array at author.ext.social_links", "items": { "type": "string", "description": "Leaf at author.ext.social_links" } }, "bio_link": { "type": [ "string", "null" ], "description": "String at author.ext.bio_link" }, "embed_html": { "type": [ "string", "null" ], "description": "String at author.ext.embed_html" }, "embed_url": { "type": [ "string", "null" ], "description": "String at author.ext.embed_url" }, "group": { "type": [ "string", "null" ], "description": "Leaf at author.ext.group" }, "search_hit": { "type": [ "object", "null" ], "description": "Nested object: author.ext.search_hit", "properties": { "match": { "type": [ "string", "null" ], "description": "Leaf at author.ext.search_hit.match" }, "title": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.title" }, "snippet": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.snippet" }, "evidence_url": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.evidence_url" }, "matched_urls": { "type": [ "array", "null" ], "description": "Array at author.ext.search_hit.matched_urls", "items": { "type": "string", "description": "String at author.ext.search_hit.matched_urls" } } } }, "blog_name": { "type": [ "string", "null" ], "description": "String at author.ext.blog_name" }, "blog_no": { "type": [ "string", "null" ], "description": "String at author.ext.blog_no" }, "visitors_today": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.visitors_today" }, "visitors_total": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.visitors_total" }, "topic": { "type": [ "string", "null" ], "description": "String at author.ext.topic" }, "power_blog": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.power_blog" }, "official_blog": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.official_blog" } } } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/user/following", "data": { "items": [ { "author": { "id": "user_0035c7", "username": "user_fcb710", "display_name": "user_e5848d", "avatar_url": "https://example.com/avatars/user_f45c30.png", "bio": "Sample comment text (redacted).", "verified": false, "followers": 833961, "following": 167, "posts_count": 3114, "likes_count": 45301840, "url": "https://example.com/user_615544", "location": null, "private": false, "joined_at": "user_77c887" } }, { "author": { "id": "user_afb6ca", "username": "user_f73e53", "display_name": "user_698dd9", "avatar_url": "https://example.com/avatars/user_dcd51f.png", "bio": null, "verified": false, "followers": 1564, "following": 217, "posts_count": 980, "likes_count": 69167, "url": "https://example.com/user_0402d9", "location": null, "private": false, "joined_at": "user_edfcbb" } } ], "total": 96, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": null, "has_more": false, "page_size": 96 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T13:11:08.149Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/user/live": { "get": { "summary": "Get TikTok user live stream", "description": "Returns the current live-stream state for a TikTok user: `is_live`, and when the account is or has recently been live, the room (title, cover, start time, viewer stats). An account that exists but has never streamed returns `is_live: false` with an empty room and bills 1 credit; a handle that does not exist returns 404 at 0 credits. Answers are cached for at most 60 seconds.", "tags": [ "tiktok" ], "operationId": "get_tiktok_user_live", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "TikTok username without the @ symbol", "schema": { "type": "string" }, "example": "charlidamelio" }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/user/live" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "metrics": { "type": "object", "description": "Key performance metrics", "properties": { "total_views": { "type": "integer", "description": "Total view count" }, "total_likes": { "type": "integer", "description": "Total like count" }, "total_comments": { "type": "integer", "description": "Total comment count" }, "engagement_rate": { "type": "number", "description": "Computed engagement rate (0-1)" } } }, "period": { "type": [ "string", "null" ], "description": "Time period for the analytics data" }, "breakdown": { "type": [ "array", "null" ], "description": "Per-item or per-period breakdown", "items": { "type": "object", "description": "Breakdown entry" } }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } } }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/user/live", "data": { "is_live": false, "liveRoom": { "coverUrl": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:720:720.webp?dr=9640&refresh_token=56fcdd97&x-expires=1791126000&x-signature=LbU2VeaTrobL41AcsiIxnKl8DLU%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=fdd36af4&idc=useast5", "squareCoverImg": "", "title": "", "startTime": 1781762987, "status": 4, "paidEvent": { "event_id": 0, "paid_type": 0 }, "liveSubOnly": 0, "liveRoomMode": 0, "gameTagId": 0, "liveRoomStats": { "enterCount": 1, "userCount": 1 }, "streamData": { "pull_data": { "options": { "default_preview_quality": { "icon_type": 0, "level": 0, "name": "user_e3b0c4", "resolution": "", "sdk_key": "", "v_codec": "" }, "default_quality": { "icon_type": 0, "level": 0, "name": "720p", "resolution": "", "sdk_key": "hd", "v_codec": "" }, "forced_low_latency": false, "max_drm_lenient_size": "", "max_drm_lenient_size_backup": "", "qualities": [ { "icon_type": 0, "level": 3, "name": "720p", "resolution": "", "sdk_key": "hd", "v_codec": "" } ], "show_quality_button": false, "support_low_latency": false }, "stream_data": "{\"common\":{\"session_id\":\"173-20261002154045D09C2FEC212F14E00718\",\"room_id\":7652613286029986574,\"rule_ids\":\"{\\\"ab_version_trace\\\":null,\\\"sched\\\":\\\"{\\\\\\\"ids\\\\\\\":[\\\\\\\"ex_83502(Weight:100)\\\\\\\"],\\\\\\\"result\\\\\\\":{\\\\\\\"rule_id\\\\\\\":83502,\\\\\\\"rule_name\\\\\\\":\\\\\\\"[TailNumber]FCDN pull FCDN push in US/pct:50\\\\\\\",\\\\\\\"category\\\\\\\":\\\\\\\"Capacity\\\\\\\",\\\\\\\"hit\\\\\\\":\\\\\\\"exclusive\\\\\\\",\\\\\\\"cdn\\\\\\\":2041,\\\\\\\"cdn_name\\\\\\\":\\\\\\\"fcdn\\\\\\\"}}\\\"}\",\"peer_anchor_level\":51,\"default_audio_track\":\"en\"},\"data\":{\"hd\":{\"main\":{\"flv\":\"https://pull-flv-l77-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_hd.flv?expire=1792165245&sign=5622ff1075ce70e4ebc4ad3ea0370bc9\",\"hls\":\"\",\"cmaf\":\"\",\"dash\":\"\",\"lls\":\"\",\"tsl\":\"\",\"tile\":\"\",\"rtc\":\"\",\"sdk_params\":\"{\\\"VCodec\\\":\\\"h264\\\",\\\"stream_suffix\\\":\\\"hd\\\",\\\"vbitrate\\\":1000000,\\\"resolution\\\":\\\"540x1080\\\",\\\"gop\\\":4,\\\"cdn_name\\\":\\\"cdn77\\\"}\"},\"backup\":{\"flv\":\"https://pull-f5-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_hd.flv?expire=1792165245&sign=28446850157ee7072a9903bd47f84e7b\",\"hls\":\"https://pull-hls-f16-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_hd/index.m3u8?expire=1792165245&sign=764a37111c9bcee83db8a32cc22b7faf\",\"cmaf\":\"https://pull-f5-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_hd/index.mpd?auth_mode=2&expire=1792165245&sign=595017fa3af35c09046c00dea462d2ff\",\"dash\":\"\",\"lls\":\"https://pull-f5-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_hd.sdp?expire=1792165245&sign=bd20e7c3d91958eb6ba3ffc477a21b9a\",\"tsl\":\"\",\"tile\":\"\",\"rtc\":\"\",\"sdk_params\":\"{\\\"VCodec\\\":\\\"h264\\\",\\\"cmaf_auth\\\":\\\"auth_mode=2\\\\u0026expire=1792165245\\\\u0026sign=ce75c5e367c4693249a713d7b7373356\\\",\\\"cdn_name\\\":\\\"fcdn\\\",\\\"stream_suffix\\\":\\\"hd\\\",\\\"vbitrate\\\":1000000,\\\"resolution\\\":\\\"720x1440\\\",\\\"gop\\\":4}\"}},\"ao\":{\"main\":{\"flv\":\"https://pull-flv-l77-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583.flv?expire=1792165245&sign=6f1542db4760a61dedc6d434ff9cfeba&only_audio=1\",\"hls\":\"\",\"cmaf\":\"\",\"dash\":\"\",\"lls\":\"\",\"tsl\":\"\",\"tile\":\"\",\"rtc\":\"\",\"sdk_params\":\"{\\\"VCodec\\\":\\\"h264\\\",\\\"vbitrate\\\":0,\\\"resolution\\\":\\\"\\\",\\\"gop\\\":4,\\\"cdn_name\\\":\\\"cdn77\\\",\\\"stream_suffix\\\":\\\"ao\\\"}\"},\"backup\":{\"flv\":\"https://pull-f5-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583.flv?expire=1792165245&sign=3095056c6b804592a1f0d7476b49bfd0&only_audio=1\",\"hls\":\"\",\"cmaf\":\"https://pull-f5-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_ao/index.mpd?auth_mode=2&expire=1792165245&sign=4a2ce4dc6cf1d732da55eb97f476b94b\",\"dash\":\"\",\"lls\":\"\",\"tsl\":\"\",\"tile\":\"\",\"rtc\":\"\",\"sdk_params\":\"{\\\"VCodec\\\":\\\"h264\\\",\\\"cmaf_auth\\\":\\\"auth_mode=2\\\\u0026expire=1792165245\\\\u0026sign=ce75c5e367c4693249a713d7b7373356\\\",\\\"vbitrate\\\":0,\\\"resolution\\\":\\\"\\\",\\\"gop\\\":4,\\\"cdn_name\\\":\\\"fcdn\\\",\\\"stream_suffix\\\":\\\"ao\\\"}\"}}}}" }, "push_data": { "push_stream_level": 0, "resolution_params": {}, "stream_data": "" } }, "streamId": "3578336603596653583", "multiStreamScene": 0, "multiStreamSource": 0, "hevcStreamData": { "pull_data": { "options": { "default_preview_quality": { "icon_type": 0, "level": 0, "name": "user_e3b0c4", "resolution": "", "sdk_key": "", "v_codec": "" }, "default_quality": { "icon_type": 0, "level": 0, "name": "720p", "resolution": "", "sdk_key": "hd", "v_codec": "" }, "forced_low_latency": false, "max_drm_lenient_size": "", "max_drm_lenient_size_backup": "", "qualities": [ { "icon_type": 0, "level": 10, "name": "Original", "resolution": "", "sdk_key": "origin", "v_codec": "" }, { "icon_type": 0, "level": 3, "name": "720p", "resolution": "", "sdk_key": "hd", "v_codec": "" } ], "show_quality_button": false, "support_low_latency": false }, "stream_data": "{\"common\":{\"session_id\":\"173-20261002154045D09C2FEC212F14E00718\",\"room_id\":7652613286029986574,\"rule_ids\":\"{\\\"ab_version_trace\\\":null,\\\"sched\\\":\\\"{\\\\\\\"ids\\\\\\\":[\\\\\\\"ex_83502(Weight:100)\\\\\\\"],\\\\\\\"result\\\\\\\":{\\\\\\\"category\\\\\\\":\\\\\\\"Capacity\\\\\\\",\\\\\\\"hit\\\\\\\":\\\\\\\"exclusive\\\\\\\",\\\\\\\"cdn\\\\\\\":2041,\\\\\\\"cdn_name\\\\\\\":\\\\\\\"fcdn\\\\\\\",\\\\\\\"rule_id\\\\\\\":83502,\\\\\\\"rule_name\\\\\\\":\\\\\\\"[TailNumber]FCDN pull FCDN push in US/pct:50\\\\\\\"}}\\\"}\",\"peer_anchor_level\":51,\"default_audio_track\":\"en\"},\"data\":{\"hd\":{\"main\":{\"flv\":\"https://pull-flv-l77-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_hd5.flv?expire=1792165245&sign=5944500a5c0d533388bf1603851634f0\",\"hls\":\"\",\"cmaf\":\"\",\"dash\":\"\",\"lls\":\"\",\"tsl\":\"\",\"tile\":\"\",\"rtc\":\"\",\"sdk_params\":\"{\\\"VCodec\\\":\\\"h265\\\",\\\"stream_suffix\\\":\\\"hd5\\\",\\\"vbitrate\\\":1350000,\\\"resolution\\\":\\\"540x1080\\\",\\\"gop\\\":4,\\\"cdn_name\\\":\\\"cdn77\\\"}\"},\"backup\":{\"flv\":\"https://pull-f5-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_hd5.flv?expire=1792165245&sign=1f59024f1e3020f3412807dacd236ccd\",\"hls\":\"https://pull-hls-f16-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_hd5/index.m3u8?expire=1792165245&sign=d1ee897eed1d490b367e754a6296b443\",\"cmaf\":\"https://pull-f5-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_hd5/index.mpd?auth_mode=2&expire=1792165245&sign=e95ee747733cedb52700c48ccbc4f912\",\"dash\":\"\",\"lls\":\"https://pull-f5-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_hd5.sdp?expire=1792165245&sign=7fb901041c56c5184270f4388d0b2a23\",\"tsl\":\"\",\"tile\":\"\",\"rtc\":\"\",\"sdk_params\":\"{\\\"VCodec\\\":\\\"h265\\\",\\\"cmaf_auth\\\":\\\"auth_mode=2\\\\u0026expire=1792165245\\\\u0026sign=ce75c5e367c4693249a713d7b7373356\\\",\\\"vbitrate\\\":1350000,\\\"resolution\\\":\\\"720x1440\\\",\\\"gop\\\":4,\\\"cdn_name\\\":\\\"fcdn\\\",\\\"stream_suffix\\\":\\\"hd5\\\"}\"}},\"sd\":{\"main\":{\"flv\":\"https://pull-flv-l77-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_zsd5.flv?expire=1792165245&sign=a54f8784b1e1cddc402bd386b3fe987d\",\"hls\":\"\",\"cmaf\":\"\",\"dash\":\"\",\"lls\":\"\",\"tsl\":\"\",\"tile\":\"\",\"rtc\":\"\",\"sdk_params\":\"{\\\"VCodec\\\":\\\"h265\\\",\\\"cdn_name\\\":\\\"cdn77\\\",\\\"stream_suffix\\\":\\\"zsd5\\\",\\\"vbitrate\\\":800000,\\\"resolution\\\":\\\"544x1088\\\",\\\"gop\\\":4}\"},\"backup\":{\"flv\":\"https://pull-f5-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_zsd5.flv?expire=1792165245&sign=53726a3999cfcbb1d18512562d54198c\",\"hls\":\"https://pull-hls-f16-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_zsd5/index.m3u8?expire=1792165245&sign=d6432c29c092a1a087a3e217e458b74e\",\"cmaf\":\"https://pull-f5-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_zsd5/index.mpd?auth_mode=2&expire=1792165245&sign=a3eb1f7f6ac15e0c893026ec9bfd5b38\",\"dash\":\"\",\"lls\":\"https://pull-f5-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_zsd5.sdp?expire=1792165245&sign=81e2996ff3897a7214a3c455ef9deb01\",\"tsl\":\"\",\"tile\":\"\",\"rtc\":\"\",\"sdk_params\":\"{\\\"VCodec\\\":\\\"h265\\\",\\\"cmaf_auth\\\":\\\"auth_mode=2\\\\u0026expire=1792165245\\\\u0026sign=ce75c5e367c4693249a713d7b7373356\\\",\\\"stream_suffix\\\":\\\"zsd5\\\",\\\"vbitrate\\\":800000,\\\"resolution\\\":\\\"576x1152\\\",\\\"gop\\\":4,\\\"cdn_name\\\":\\\"fcdn\\\"}\"}},\"origin\":{\"main\":{\"flv\":\"https://pull-flv-l77-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583.flv?expire=1792165245&sign=6f1542db4760a61dedc6d434ff9cfeba\",\"hls\":\"\",\"cmaf\":\"\",\"dash\":\"\",\"lls\":\"\",\"tsl\":\"\",\"tile\":\"\",\"rtc\":\"\",\"sdk_params\":\"{\\\"VCodec\\\":\\\"h265\\\",\\\"resolution\\\":\\\"960x1920\\\",\\\"gop\\\":4,\\\"cdn_name\\\":\\\"cdn77\\\",\\\"vbitrate\\\":2824000}\"},\"backup\":{\"flv\":\"https://pull-f5-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583.flv?expire=1792165245&sign=3095056c6b804592a1f0d7476b49bfd0\",\"hls\":\"https://pull-hls-f16-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583/index.m3u8?expire=1792165245&sign=924ea1cc326b939b7a834699d6ab11c4\",\"cmaf\":\"https://pull-f5-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583/index.mpd?auth_mode=2&expire=1792165245&sign=ce75c5e367c4693249a713d7b7373356\",\"dash\":\"\",\"lls\":\"https://pull-f5-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583.sdp?expire=1792165245&sign=e872b66824f3a2c10cc581415a9c7ffd\",\"tsl\":\"\",\"tile\":\"\",\"rtc\":\"\",\"sdk_params\":\"{\\\"VCodec\\\":\\\"h265\\\",\\\"cmaf_auth\\\":\\\"auth_mode=2\\\\u0026expire=1792165245\\\\u0026sign=ce75c5e367c4693249a713d7b7373356\\\",\\\"resolution\\\":\\\"960x1920\\\",\\\"gop\\\":4,\\\"cdn_name\\\":\\\"fcdn\\\",\\\"vbitrate\\\":2824000}\"}},\"ao\":{\"main\":{\"flv\":\"https://pull-flv-l77-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583.flv?expire=1792165245&sign=6f1542db4760a61dedc6d434ff9cfeba&only_audio=1\",\"hls\":\"\",\"cmaf\":\"\",\"dash\":\"\",\"lls\":\"\",\"tsl\":\"\",\"tile\":\"\",\"rtc\":\"\",\"sdk_params\":\"{\\\"VCodec\\\":\\\"h264\\\",\\\"cdn_name\\\":\\\"cdn77\\\",\\\"stream_suffix\\\":\\\"ao\\\",\\\"vbitrate\\\":0,\\\"resolution\\\":\\\"\\\",\\\"gop\\\":4}\"},\"backup\":{\"flv\":\"https://pull-f5-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583.flv?expire=1792165245&sign=3095056c6b804592a1f0d7476b49bfd0&only_audio=1\",\"hls\":\"\",\"cmaf\":\"https://pull-f5-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_ao/index.mpd?auth_mode=2&expire=1792165245&sign=4a2ce4dc6cf1d732da55eb97f476b94b\",\"dash\":\"\",\"lls\":\"\",\"tsl\":\"\",\"tile\":\"\",\"rtc\":\"\",\"sdk_params\":\"{\\\"VCodec\\\":\\\"h264\\\",\\\"cmaf_auth\\\":\\\"auth_mode=2\\\\u0026expire=1792165245\\\\u0026sign=ce75c5e367c4693249a713d7b7373356\\\",\\\"vbitrate\\\":0,\\\"resolution\\\":\\\"\\\",\\\"gop\\\":4,\\\"cdn_name\\\":\\\"fcdn\\\",\\\"stream_suffix\\\":\\\"ao\\\"}\"}},\"ld\":{\"main\":{\"flv\":\"https://pull-flv-l77-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_ld5.flv?expire=1792165245&sign=37311d006ae9553db8b5d5f23d7f81f2\",\"hls\":\"\",\"cmaf\":\"\",\"dash\":\"\",\"lls\":\"\",\"tsl\":\"\",\"tile\":\"\",\"rtc\":\"\",\"sdk_params\":\"{\\\"VCodec\\\":\\\"h265\\\",\\\"resolution\\\":\\\"360x720\\\",\\\"gop\\\":4,\\\"cdn_name\\\":\\\"cdn77\\\",\\\"stream_suffix\\\":\\\"ld5\\\",\\\"vbitrate\\\":400000}\"},\"backup\":{\"flv\":\"https://pull-f5-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_ld5.flv?expire=1792165245&sign=a5a997485f2d381c935220eda74e05f6\",\"hls\":\"https://pull-hls-f16-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_ld5/index.m3u8?expire=1792165245&sign=52da11094c070c4354f267fa10501d2e\",\"cmaf\":\"https://pull-f5-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_ld5/index.mpd?auth_mode=2&expire=1792165245&sign=ec78fba68c9977778566bcb09b51bd51\",\"dash\":\"\",\"lls\":\"https://pull-f5-tt01.tiktokcdn-us.com/stage/stream-3578336603596653583_ld5.sdp?expire=1792165245&sign=2e5926af1d6a27bd28215dccabb41612\",\"tsl\":\"\",\"tile\":\"\",\"rtc\":\"\",\"sdk_params\":\"{\\\"VCodec\\\":\\\"h265\\\",\\\"cmaf_auth\\\":\\\"auth_mode=2\\\\u0026expire=1792165245\\\\u0026sign=ce75c5e367c4693249a713d7b7373356\\\",\\\"stream_suffix\\\":\\\"ld5\\\",\\\"vbitrate\\\":400000,\\\"resolution\\\":\\\"480x960\\\",\\\"gop\\\":0,\\\"cdn_name\\\":\\\"fcdn\\\"}\"}}}}" }, "push_data": { "push_stream_level": 0, "resolution_params": {}, "stream_data": "" } } }, "liveRoomUserInfo": { "avatarLarger": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.webp?dr=9640&refresh_token=90887632&x-expires=1791126000&x-signature=qeLffpNjBQKEgkR0LuDTnFCQDLs%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=fdd36af4&idc=useast5", "avatarMedium": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:720:720.webp?dr=9640&refresh_token=b8f3a2b5&x-expires=1791126000&x-signature=ZYelBIQxHyB3Hw%2B8MdPv8vAWAP0%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=fdd36af4&idc=useast5", "avatarThumb": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:100:100.webp?dr=9640&refresh_token=226af91a&x-expires=1791126000&x-signature=3wTMz5cffHFj0NJhfqBEgYylLHE%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=fdd36af4&idc=useast5", "id": "5831967", "nickname": "charli d’amelio", "secUid": "MS4wLjABAAAA-VASjiXTh7wDDyXvjk10VFhMWUAoxr8bgfO1kAL1-9s", "secret": false, "uniqueId": "charlidamelio", "verified": true, "roomId": "7652613286029986574", "signature": "orca enthusiast\nmeg thee stallion fan\ni post on youtube on saturdays (for the most part)", "status": 4, "followStatus": 0, "followingCount": 1442, "followerCount": 160316634 } }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T15:40:44.238Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/post/transcript": { "get": { "summary": "Get TikTok video transcript", "description": "Returns the transcript of a TikTok video. Supports auto-generated captions and AI-powered transcription as fallback. `transcript` is one string in one of two forms, and `transcript_format` names it: `webvtt` (WebVTT cues with timestamps) when it comes from the video's caption track or from AI transcription of a longer video, `text` (plain text, with `duration_seconds` and `duration_minutes`) when it comes from AI transcription of a shorter one. Read `transcript_format` rather than guessing from the video's length. A video over 2 minutes is transcribed on demand and can take a minute or more, so allow up to 300 seconds before your HTTP client times out.", "tags": [ "tiktok" ], "operationId": "get_tiktok_post_transcript", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "premium", "x-credit-cost": 10, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full URL of the TikTok video", "schema": { "type": "string" }, "example": "https://www.tiktok.com/@stoolpresidente/video/7499229683859426602" }, { "name": "language", "in": "query", "required": false, "description": "Language of the transcript. 2 letter language code, ie 'en', 'es', 'fr', 'de', 'it', 'ja', 'ko', 'zh'. Selects the caption track, and is passed to AI transcription of a longer video as the spoken language. Without it, AI transcription detects the language itself and can mistake a less common one for English, so set it when you know the language. If AI transcription of a longer video cannot transcribe the language you set, the request returns 404 RESOURCE_NOT_FOUND with `error.details.reason: language_unsupported` at 0 credits rather than a transcript in another language; retrying returns the same result.", "schema": { "type": "string" } }, { "name": "use_ai_as_fallback", "in": "query", "required": false, "description": "Set to 'true' to fall back to AI transcription when the video has no captions. Included in the endpoint's 10 credits (no surcharge). AI transcription covers videos up to 10 minutes (600 seconds): a longer video with no captions returns 400 INVALID_REQUEST with `error.details.reason: video_too_long`, `duration_seconds` and `max_seconds`, free and deterministic, so retrying returns the same answer.", "schema": { "type": "string" } }, { "name": "moments", "in": "query", "required": false, "description": "Optional CSV of moment kinds to find: brand, sponsor_read, product_demo, call_to_action. Returns data.moments = [{ kind, start_ms, end_ms, quote }] when the transcript has timestamps. Price of the extra step is an owner decision; today it does not add credits.", "schema": { "type": "string" } }, { "name": "brand", "in": "query", "required": false, "description": "Optional, with moments=. The company or product to look for, so a namesake is not counted.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Optional question about the video, up to 300 characters, for example q=what discount code do they give. Returns data.moments = [{ kind: \"answers_query\", start_ms, end_ms, quote }] for each stretch of about six transcript lines that states the answer: a stretch that only shares the topic is left out, and a question the video never answers returns an empty list. The quote is one line copied from the transcript and the times come from the segments. Send moments= or q=, not both. If the step cannot run, the transcript is returned without data.moments and data._warnings carries moments_unavailable. Today it does not add credits.", "schema": { "type": "string" } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/post/transcript" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "transcript": { "type": [ "string", "null" ], "description": "Full transcript text. Plain string for TikTok/Facebook/Twitter; see `transcripts` for Instagram and the segmented YouTube shape." }, "transcript_format": { "type": "string", "enum": [ "webvtt", "text" ], "description": "TikTok only: the form of the `transcript` string. `webvtt` is WebVTT cues with timestamps (a caption track, or AI transcription of a longer video); `text` is plain text (AI transcription of a shorter video, which also returns `duration_seconds` and `duration_minutes`). Absent on other platforms and when there is no transcript." }, "transcripts": { "type": [ "array", "null" ], "description": "Instagram transcript entries. Each item has a `text` field with the full transcript for that track.", "items": { "type": "object", "description": "Transcript track", "properties": { "text": { "type": "string", "description": "Transcript text" } } } }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } } }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/post/transcript", "data": { "id": "7499229683859426602", "url": "https://www.tiktok.com/@stoolpresidente/video/7499229683859426602", "transcript": "WEBVTT\n\n\n00:00:00.180 --> 00:00:01.740\nAlright, pizza review time.\n\n00:00:01.741 --> 00:00:03.701\nSal's Pizza Factory. Oh,\n\n00:00:03.702 --> 00:00:05.701\nit's fucking pouring. We're in Charlotte.\n\n00:00:05.702 --> 00:00:07.781\nAlright man, any chance I get a real quick picture?\n\n00:00:07.782 --> 00:00:09.901\nJack or Dwight Howard? I gotta pick one.\n\n00:00:09.902 --> 00:00:10.861\nYeah, Jack.\n\n00:00:10.862 --> 00:00:12.301\nYeah, easy, right?\n\n00:00:12.302 --> 00:00:13.981\nWe're still Jason Williams still with us?\n\n00:00:13.982 --> 00:00:16.381\nYeah, he on the plane right over,\n\n00:00:16.382 --> 00:00:18.261\nout of the blue. Said the following.\n\n00:00:18.262 --> 00:00:21.141\nHe would take Dwight Howard over Shaq at center.\n\n00:00:21.142 --> 00:00:23.461\nAnd says he lie about it for the rest of his life\n\n00:00:23.462 --> 00:00:25.341\nand would never admit to saying that.\n\n00:00:25.342 --> 00:00:28.441\nListen, y'all seen him on his camera more more times than me.\n\n00:00:28.500 --> 00:00:31.980\nHe's lying. This is an outrageous pizza.\n\n00:00:31.981 --> 00:00:33.601\nI don't even know that they cut it.\n\n00:00:35.340 --> 00:00:36.620\nWow, very hot.\n\n00:00:36.621 --> 00:00:37.701\nAll right, it is cut.\n\n00:00:37.702 --> 00:00:39.821\nThat's a lava soup in the middle.\n\n00:00:39.822 --> 00:00:42.621\nIt is going back and forth like crazy.\n\n00:00:42.622 --> 00:00:45.301\nYou need some silverware. I really do want to let this cool\n\n00:00:45.302 --> 00:00:46.821\nso we can talk about you to White House.\n\n00:00:46.822 --> 00:00:48.361\nNo, it's shut up.\n\n00:00:49.580 --> 00:00:51.200\nAnd. But then he said if.\n\n00:00:51.740 --> 00:00:53.620\nIf. If he was starting five,\n\n00:00:53.621 --> 00:00:54.981\nyou would take Shaq? Yes,\n\n00:00:54.982 --> 00:00:56.541\nbut Dwight Howard's the best center.\n\n00:00:56.542 --> 00:01:00.241\nShaq is the most dominant center ever to play the game of basketball.\n\n00:01:01.140 --> 00:01:02.520\nWhy would you take Drake out?\n\n00:01:02.620 --> 00:01:05.460\nDefensive purpose. So you're like math GM?\n\n00:01:05.461 --> 00:01:08.161\nGet rid of Luca and get a defensive guy in there.\n\n00:01:08.260 --> 00:01:09.660\nListen, I'm nothing like Nico\n\n00:01:09.661 --> 00:01:11.341\nand I've never GM the team in my life\n\n00:01:11.342 --> 00:01:12.621\nand I'm guarantee I'm better.\n\n00:01:12.622 --> 00:01:14.901\nI'd never make that deal. That was the dumbest deal ever.\n\n00:01:14.902 --> 00:01:18.221\nTo be made. This tastes better than how sloppy it is.\n\n00:01:18.222 --> 00:01:19.821\n7 3. It's not bad at all,\n\n00:01:19.822 --> 00:01:20.741\nthis. Actually,\n\n00:01:20.742 --> 00:01:23.541\nI'm not just saying it. This eats way better than it looks.\n\n00:01:23.542 --> 00:01:24.821\nI don't know whether it is.\n\n00:01:24.822 --> 00:01:25.981\nHustle this out of the oven.\n\n00:01:25.982 --> 00:01:26.821\nAll right. Do you want some?\n\n00:01:26.822 --> 00:01:27.341\nNo, sir.\n\n00:01:27.342 --> 00:01:28.741\nAll right. I don't wanna burn the river in my mouth.\n\n00:01:28.742 --> 00:01:29.995\nAll right. That's gonna be a pro.\n" }, "credits_used": 0, "request_id": "req_example000000", "cached": true, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T12:51:28.487Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/video/screen-text": { "get": { "summary": "Get TikTok video on-screen text", "description": "Extracts the text shown ON a TikTok post itself: the overlay captions creators put on screen, which the regular caption and transcript never carry. Two layers are merged: native text-sticker data (present when the creator used TikTok's built-in text tool) and AI OCR of the post's images, which also catches text burned in with editors like CapCut that no data provider returns. What the OCR layer reads depends on the post. On a video, the cover frame by default, so text that appears later in the video is not read; with `frames=all` the whole video is read instead, up to 3 minutes (180 seconds), and the response adds `subtitles` (on-screen captions of the speech, kept apart from `texts`), a `timeline` of every text block with `at_seconds`, the second it first appears, and `kind` (text or subtitle), and `duration_seconds`. On a photo post (pass its `/photo/` link), every slide in order, 10 slides a call: the first 10 by default, and the next 10 with `slide_offset=10`; a longer photo post's response carries a warning giving its full slide count, and `slide_offset` and `next_slide_offset` say where this call started and which offset reads the rest (null when every slide has been read). `texts` is the deduplicated union in reading order; `native_texts` and `ocr_texts` expose each layer separately and `source` says which layers produced data. On a photo post, `images` lists each slide read with its own `texts` and its 0-based `index`, so you know which slide said what. A post with no on-screen text returns an empty `texts` array (that is a real answer, not an error). Costs 5 credits for a video's cover or for each call on a photo post (10 slides), and 10 credits for a whole video with `frames=all`; auto-refunds when the post lookup or the whole extraction fails, or when a parameter does not fit the post.", "tags": [ "tiktok" ], "operationId": "get_tiktok_video_screen_text", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "x-credit-cost-min": 5, "x-credit-cost-max": 10, "x-credit-cost-formula": "5 credits a call, the same for a video's cover or a photo post page of 10 slides. 10 credits with `frames=all` on a video; when the post is a photo post, or the video cannot be read and the cover is read instead, the call costs 5 and the response says so in `warnings`. Refunded when the post cannot be found, when nothing on it could be read, or when a parameter does not fit the post (a `slide_offset` past the last slide or on a video, a video over 180 seconds with `frames=all`).", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full URL of the TikTok video or photo post (a `/video/` or `/photo/` link)", "schema": { "type": "string" }, "example": "https://www.tiktok.com/@stoolpresidente/video/7499229683859426602" }, { "name": "frames", "in": "query", "required": false, "description": "What to read on a video. `cover` (the default) reads the cover frame for 5 credits. `all` reads the whole video, up to 180 seconds, for 10 credits, and adds `subtitles`, `timeline` and `duration_seconds`. Has no effect on photo posts, which are read as usual for 5 credits.", "schema": { "type": "string", "enum": [ "cover", "all" ] } }, { "name": "slide_offset", "in": "query", "required": false, "description": "Photo posts only: the 0-based index of the first slide to read, 10 slides a call. Default 0. `slide_offset=10` reads slides 11 to 20. Each slide in `images` keeps its index in the whole post, and `next_slide_offset` gives the value for the next call.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/video/screen-text" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "metrics": { "type": "object", "description": "Key performance metrics", "properties": { "total_views": { "type": "integer", "description": "Total view count" }, "total_likes": { "type": "integer", "description": "Total like count" }, "total_comments": { "type": "integer", "description": "Total comment count" }, "engagement_rate": { "type": "number", "description": "Computed engagement rate (0-1)" } } }, "period": { "type": [ "string", "null" ], "description": "Time period for the analytics data" }, "breakdown": { "type": [ "array", "null" ], "description": "Per-item or per-period breakdown", "items": { "type": "object", "description": "Breakdown entry" } }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } } }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/video/screen-text", "data": { "video_id": "7660536627479022870", "url": "https://www.tiktok.com/@disneymusic/video/7660536627479022870", "texts": [ "Enjoy 57 minutes of Nostalgic \nDISNEY Songs" ], "native_texts": [ "Enjoy 57 minutes of Nostalgic \nDISNEY Songs" ], "ocr_texts": [ "Enjoy 57 minutes of Nostalgic DISNEY Songs" ], "source": "native+ocr", "media_type": "video", "frame": "cover" }, "credits_used": 5, "credits_remaining": 95, "request_id": "req-a1b2c3d4e5f6", "cached": false } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/song": { "get": { "summary": "Get TikTok song details", "description": "Returns details about a specific TikTok sound/song including title, artist, duration, and cover image. The number of videos using the sound is published twice: `post.engagement.views` keeps the value this endpoint has always returned, and `post.ext.use_count` is that same number labelled as a video count (`post.ext.use_count_unit` is `videos`). It is not a play count. To record this count every day, create a Monitor that tracks `post.engagement.views`; see /docs/recipes/track-sound-growth.", "tags": [ "tiktok" ], "operationId": "get_tiktok_song", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "clipId", "in": "query", "required": true, "description": "TikTok sound/song clip ID", "schema": { "type": "string" }, "example": "7439295283975702544" }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/song" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } } }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached" ] }, "example": { "success": true, "platform": "youtube", "endpoint": "/v1/youtube/video", "data": { "post": { "id": "dQw4w9WgXcQ", "content": { "text": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)", "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg", "duration_seconds": 214, "media_urls": "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw" }, "author": { "username": "UCuAXFkgsw1L7xaCfnd5JJOw", "display_name": "Rick Astley", "avatar_url": null, "verified": null }, "engagement": { "views": 1789065639, "likes": 19216844, "comments": 2443809, "shares": null, "saves": null }, "published_at": "2009-10-25T06:57:33Z", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "ext": { "content_type": "video", "tags": [ "rick astley", "Never Gonna Give You Up", "nggyu", "never gonna give you up lyrics", "rick rolled", "Rick Roll", "rick astley official", "rickrolled", "Fortnite song", "Fortnite event", "Fortnite dance", "fortnite never gonna give you up", "rick roll", "rickrolling", "rick rolling", "never gonna give you up", "80s music", "rick astley new", "animated video", "rickroll", "meme songs", "never gonna give u up lyrics", "Rick Astley 2022", "never gonna let you down", "animated", "rick rolls 2022", "never gonna give you up karaoke" ], "categoryId": "10", "categoryTitle": "Music", "topicCategories": [ "https://en.wikipedia.org/wiki/Electronic_music", "https://en.wikipedia.org/wiki/Music", "https://en.wikipedia.org/wiki/Pop_music", "https://en.wikipedia.org/wiki/Rhythm_and_blues", "https://en.wikipedia.org/wiki/Soul_music" ], "duration": "PT3M34S", "license": "youtube", "madeForKids": false, "defaultAudioLanguage": "en", "hasPaidProductPlacement": false, "caption": "true", "description": "The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100. It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”. The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2. The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo", "default_language": "en" }, "flags": { "deleted": false, "nsfw": null, "spoiler": null, "pinned": null } }, "computed": { "engagement_rate": 0.012107, "language": "en", "content_category": "entertainment", "estimated_reach": 2146878767 } }, "credits_used": 1, "credits_remaining": 9999, "request_id": "req-8Kq2ZmR4vT9xLb3P", "cached": false, "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/song/videos": { "get": { "summary": "List TikTok videos using a song", "description": "Returns videos that use a specific TikTok sound/song. Each video includes engagement metrics, author info, and caption. `data.adoption` counts those videos by the day in `published_at`, says how many rows had no date, and sets `returning` when an old sound's first page is mostly from the last three days. The curve is global: it counts every row whatever its country. Each row carries `post.ext.region`, the country the video is registered to, when the source sends it, and `post.ext.matched_song_id`, the catalogue song TikTok matched the sound to, which an official clip and the original sounds creators upload with it share across different clipIds. `use=1` also files each caption into lip-sync, tutorial, before-and-after, greeting-card reveal, or none. No extra credits. To record how many videos use the sound every day, create a Monitor on /v1/tiktok/song that tracks `post.engagement.views`; see /docs/recipes/track-sound-growth.", "tags": [ "tiktok" ], "operationId": "get_tiktok_song_videos", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-socialcrawl-oneOf": [ [ "clipId" ] ], "parameters": [ { "name": "clipId", "in": "query", "required": false, "description": "TikTok sound/song clip ID (one of: clipId; at least one required)", "schema": { "type": "string" }, "example": "7439295283975702544" }, { "name": "cursor", "in": "query", "required": false, "description": "The cursor to get the next page of results.", "schema": { "type": "integer" } }, { "name": "use", "in": "query", "required": false, "description": "Optional. 1 adds data.adoption.uses, a count of what the captions are doing with the sound. Omit it and the date histogram is still returned.", "schema": { "type": "boolean" } }, { "name": "since", "in": "query", "required": false, "description": "Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.", "schema": { "type": "string" } }, { "name": "max_pages", "in": "query", "required": false, "description": "1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "max_items", "in": "query", "required": false, "description": "1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: \"max_items\"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`\"time_budget\"`): send the returned cursor with the same params to continue.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "max_credits", "in": "query", "required": false, "description": "1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: \"max_credits\"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/song/videos" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical post wrappers ({ post, computed })", "items": { "type": "object", "description": "Canonical post wrapper", "properties": { "post": { "type": "object", "description": "Canonical Post object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "integer", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "integer", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "integer", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "integer", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "integer", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "integer", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "string", "null" ], "description": "Leaf at computed.labels" }, "labels_evidence": { "type": [ "string", "null" ], "description": "Leaf at computed.labels_evidence" } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/song/videos", "data": { "items": [ { "post": { "id": "7502954579814845726", "url": "https://www.tiktok.com/@user_b12a58/video/7502954579814845726", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://v19.tiktokcdn-us.com/f8c5691988ef6e1e6e0ccd72e0bd9dab/6abfb159/video/tos/useast8/tos-useast8-ve-0068c004-tx2/o4FcZMHoHA9XEtggE2y9QR2BVcffI09GEC6AQD/?a=1233&bti=O3YpOjQ0Zik3OjlmOm0uMjM6ZDQ0MDo%3D&&bt=2111&ft=BIcq8V~3wUxl7K2gUtIvk84jWLpie8f.QjKJH0ShgG0P3-I&mime_type=video_mp4&rc=N2UzM2Y1ZWk5OTZmZWk3ZUBpanB0cHU5cjt3MzMzaTczNEBeMi9iNmIxNl4xNWJgMi1hYSNya18tMmQ0YmNhLS1kMTJzcw%3D%3D&vvpl=1&l=202610020727309BD231023D0475CBF6F8&btag=e000b8000", "thumbnail_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oMAj6PIBJAreJfqxIxMTsLAQGeA5LIAjQEAQ7g~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=8596&refresh_token=bf9de5f6&x-expires=1791010800&x-signature=WilarDOoHURxMoDS5gfTKC56bdQ%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=f6441914&idc=useast5&biz_tag=tt_video&s=MUSIC_AWEME&sc=cover", "duration_seconds": 23.467 }, "author": { "username": "user_b12a58", "display_name": "user_abb9c0", "avatar_url": "https://example.com/avatars/user_4990ed.png", "verified": true }, "engagement": { "views": 2931313, "likes": 226854, "comments": 1581, "shares": 4541, "saves": 13446 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2025-05-10T22:56:11.000Z", "ext": { "music_id": "7439295283975702544", "author_id": "user_141317", "published_at_epoch": 1746917771 } }, "computed": { "engagement_rate": 0.079478, "language": "en", "content_category": "other", "estimated_reach": 3517576 } }, { "post": { "id": "7488972085616823582", "url": "https://www.tiktok.com/@user_9054ca/video/7488972085616823582", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://v19.tiktokcdn-us.com/30299bdc004c5881b6b9e9d4ec86d32a/6abfb14d/video/tos/useast8/tos-useast8-pve-0068-tx2/ogHsMQqBzAL2l0hiiBN4jAItCizuveCAWIEMnn/?a=1233&bti=O3YpOjQ0Zik3OjlmOm0uMjM6ZDQ0MDo%3D&&bt=850&ft=BIcq8V~3wUxl7K2gUtIvk84jWLpie8f.QjKJH0ShgG0P3-I&mime_type=video_mp4&rc=OmU0MzM7aGc1Zmg7MzlnOkBpajhob3A5cjo1eTMzaTczNEBiYDBhMV5jNl8xNWJhYGBhYSMwMGpqMmRrbWtgLS1kMTJzcw%3D%3D&vvpl=1&l=202610020727309BD231023D0475CBF6F8&btag=e000b0000", "thumbnail_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/owP3ftKLQPFOCDaIIeru3IA8CjFLaqftHAnDkE~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=8596&refresh_token=c0316759&x-expires=1791010800&x-signature=JNvg98pPOBXEpDDGmX9ygQ3I90I%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=f6441914&idc=useast5&biz_tag=tt_video&s=MUSIC_AWEME&sc=cover", "duration_seconds": 11.679 }, "author": { "username": "user_9054ca", "display_name": "user_a31704", "avatar_url": "https://example.com/avatars/user_5b2beb.png", "verified": false }, "engagement": { "views": 50695921, "likes": 8699823, "comments": 72548, "shares": 2996339, "saves": 470009 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2025-04-03T06:37:47.000Z", "ext": { "music_id": "7439295283975702544", "author_id": "user_37cf27", "published_at_epoch": 1743662267 } }, "computed": { "engagement_rate": 0.232143, "language": null, "content_category": "other", "estimated_reach": 60835105 } } ], "next_cursor": "sc2.eyJzIjoiYiIsImMiOiJzY3AuZXlKMklqb3hMQ0p4SWpwN0ltTjFjbk52Y2lJNklqRXlJaXdpYzJWaGNtTm9YMmxrSWpvaU1qQXlOakV3TURJd056STNNekE1UWtReU16RXdNak5FTURRM05VTkNSalpHT0NKOWZRIn0", "total": null, "adoption": { "policy_version": "d10-2026-09-23", "use_count_leaf": "engagement.views", "region": "global", "by_day": [ { "date": "2023-05-20", "videos": 1 }, { "date": "2024-12-13", "videos": 1 } ], "undated": 0, "dated": 13, "returning": false, "window": { "days": 760 } }, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWWlJc0ltTWlPaUp6WTNBdVpYbEtNa2xxYjNoTVEwcDRTV3B3TjBsdFRqRmpiazUyWTJsSk5rbHFSWGxKYVhkcFl6SldhR050VG05WU1teHJTV3B2YVUxcVFYbE9ha1YzVFVSSmQwNTZTVE5OZWtFMVVXdFJlVTE2UlhkTmFrNUZUVVJSTTA1VlRrTlNhbHBIVDBOS09XWlJJbjAiLCJlIjoidGlrdG9rL3NvbmcvdmlkZW9zIiwicCI6ImN1cnNvciJ9", "has_more": true, "page_size": 13 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T07:27:32.949Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/hashtags/popular": { "get": { "summary": "Read TikTok's own trending-hashtag board for a market and time window: the overall board plus 15 industry boards. Metered: 2 credits per hashtag returned, minimum 6", "description": "Returns the hashtags TikTok itself ranks as trending in a market over the last 7, 30 or 90 days, from the hashtag board TikTok publishes for advertisers. Each row is one hashtag: `content.text` is the tag (no `#`), `id` is TikTok's hashtag id and `url` its TikTok page. What the board says about it is on `ext.trend`: `rank` on the board it was read from, `posts` and `views` for the window (not the tag's lifetime totals, which is why `engagement.views` is null), `industry` / `industry_id` / `industry_label` naming that board (null for the overall board), `popularity_curve` as one relative value per day (0 to 100, peak = 100), and `top_creators` with handle, name, followers and country. **Depth: TikTok shows three hashtags per board to a reader who is not logged in, and that is what this endpoint reads.** One board is therefore three rows. Pass `industry=all` to read the overall board and all 15 industry boards in one call, typically 44 to 46 unique hashtags, which is where the niche signal is (in Germany the industry boards carried #adventskalender, #kürbis and #berufsschule while the overall board was three general tags). A hashtag that ranks on more than one board appears once and is billed once: its `rank` and `industry` fields name the first board it was read from (overall first, then the industries in TikTok's order), and `ext.trend.boards` lists every board it ranks on with its rank there, so a hashtag in the top 3 overall and on an industry board shows both. **Markets:** the 27 TikTok publishes this board for. **Not available any more:** the 120-day window, a second page, the new-to-top-100 filter, rank change, and the business-services, financial-services and life-services industries; each is refused with a 400 at no charge. **Pricing is metered at 2 credits per hashtag returned, minimum 6.** One board costs 6; `industry=all` holds 96 and settles to the rows returned (about 90). A board with no rows costs nothing.", "tags": [ "tiktok" ], "operationId": "get_tiktok_hashtags_popular", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 6, "x-credit-cost-min": 6, "x-credit-cost-max": 96, "x-credit-cost-formula": "2 credits per hashtag returned, minimum 6. One board is 6 credits. industry=all holds 96 credits (sixteen boards of three) and settles down to the hashtags actually returned, typically 88 to 92. An empty board costs nothing.", "parameters": [ { "name": "countryCode", "in": "query", "required": false, "description": "Market to read the board for, as an ISO country code. One of the 27 markets TikTok publishes the board for. Defaults to US.", "schema": { "type": "string", "enum": [ "US", "FR", "DE", "IT", "ES", "GB", "AR", "AU", "BR", "CA", "CO", "EG", "ID", "IL", "JP", "KR", "MY", "MX", "PH", "SA", "SG", "ZA", "TW", "TH", "TR", "AE", "VN" ] }, "example": "DE" }, { "name": "period", "in": "query", "required": false, "description": "Window in days: 7, 30 or 90. Defaults to 7. Each window is a different board, not a longer list.", "schema": { "type": "string", "enum": [ "7", "30", "90" ] }, "example": "7" }, { "name": "industry", "in": "query", "required": false, "description": "Which board to read. Omit for the overall board (3 hashtags). Pass an industry slug for that industry's board (3 hashtags), or `all` for the overall board plus all 15 industry boards in one call.", "schema": { "type": "string", "enum": [ "all", "education", "vehicle-and-transportation", "baby-kids-and-maternity", "beauty-and-personal-care", "tech-and-electronics", "travel", "household-products", "pets", "home-improvement", "apparel-and-accessories", "news-and-entertainment", "games", "food-and-beverage", "sports-and-outdoor", "health" ] }, "example": "all" }, { "name": "since", "in": "query", "required": false, "description": "Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.", "schema": { "type": "string" } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/hashtags/popular" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical post wrappers ({ post, computed })", "items": { "type": "object", "description": "Canonical post wrapper", "properties": { "post": { "type": "object", "description": "Canonical Post object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "integer", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "integer", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "integer", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "integer", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "integer", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "integer", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "string", "null" ], "description": "Leaf at computed.labels" }, "labels_evidence": { "type": [ "string", "null" ], "description": "Leaf at computed.labels_evidence" } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/hashtags/popular", "data": { "items": [ { "post": { "id": "7350401306668269570", "url": "https://www.tiktok.com/tag/marvelrivals", "content": { "text": "marvelrivals", "media_urls": null, "thumbnail_url": null, "duration_seconds": null }, "author": { "username": null, "display_name": null, "avatar_url": null, "verified": null }, "engagement": { "views": null, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": null, "ext": { "trend": { "rank": 3, "country_code": "DE", "period_days": 7, "posts": 31505, "views": 9983613, "industry": null, "industry_id": null, "industry_label": null, "boards": [ { "industry": null, "industry_id": null, "industry_label": null, "rank": 3 }, { "industry": "games", "industry_id": "25000000000", "industry_label": "Games", "rank": 1 } ], "popularity_curve": [ { "date": "2026-09-05", "value": 0.25150066717997976 }, { "date": "2026-09-06", "value": 0.17747966183783023 }, { "date": "2026-09-07", "value": 0 }, { "date": "2026-09-08", "value": 9.707961029648722 }, { "date": "2026-09-09", "value": 19.501874523150537 }, { "date": "2026-09-10", "value": 20.96499734263637 }, { "date": "2026-09-11", "value": 100 } ], "top_creators": [ { "username": "user_faf0d1", "display_name": "user_824eab", "followers": 5187, "country_code": "DE", "url": "https://example.com/user_c97b08" } ] } } }, "computed": { "engagement_rate": null, "language": null, "content_category": "other", "estimated_reach": null } }, { "post": { "id": "1607680521348102", "url": "https://www.tiktok.com/tag/fortnitedeutsch", "content": { "text": "fortnitedeutsch", "media_urls": null, "thumbnail_url": null, "duration_seconds": null }, "author": { "username": null, "display_name": null, "avatar_url": null, "verified": null }, "engagement": { "views": null, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": null, "ext": { "trend": { "rank": 2, "country_code": "DE", "period_days": 7, "posts": 14209, "views": 6151372, "industry": "games", "industry_id": "25000000000", "industry_label": "Games", "boards": [ { "industry": "games", "industry_id": "25000000000", "industry_label": "Games", "rank": 2 } ], "popularity_curve": [ { "date": "2026-09-05", "value": 12.367014372778716 }, { "date": "2026-09-06", "value": 21.449909109534023 }, { "date": "2026-09-07", "value": 52.11465027446083 }, { "date": "2026-09-08", "value": 72.59769202060639 }, { "date": "2026-09-09", "value": 100 }, { "date": "2026-09-10", "value": 7.596852750632019 }, { "date": "2026-09-11", "value": 0 } ], "top_creators": [ { "username": "pocax_pcx", "display_name": "PocaX", "followers": 452762, "country_code": "DE", "url": "https://www.tiktok.com/@pocax_pcx" } ] } } }, "computed": { "engagement_rate": null, "language": null, "content_category": "other", "estimated_reach": null } } ], "total": null }, "credits_used": 90, "credits_remaining": 9910, "request_id": "req-a1b2c3d4e5f6" } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/videos/popular": { "get": { "summary": "Read TikTok's own Top Videos board for the US, Japan, Vietnam, Thailand or Indonesia. Metered: 25 credits per board plus 1 per video returned", "description": "Returns the videos TikTok itself ranks at the top of its Top Videos board for a market over the last 7 or 30 days, sorted by views, engagement or 6-second views. Each row is a video: `id`, `url`, the caption at `content.text`, the cover and a video file URL (signed, expires within hours), the creator at `author.username` / `author.display_name` with `ext.author_id` and `ext.author_followers`, the upload time at `published_at`, and lifetime views at `engagement.views`. What the board says about it is on `ext.trend`: `rank`, `period_views` (views inside the window), `organic_views`, `engagement_rate`, `six_second_view_through_rate` and TikTok's `content_tags`. **Markets: TikTok publishes this board for US, JP, VN, TH and ID only.** Any other market, Germany included, is refused with a 400 at no charge; for those markets use `/v1/tiktok/hashtags/popular`, which covers 27. **The board carries no like, comment or share counts and no duration**, so those leaves are null rather than estimated. It includes paid and branded posts; `organic_views` is the only paid-versus-organic signal TikTok gives. A logged-out reader of TikTok's page sees the top four, and ranks 1 to 4 were checked against it; deeper ranks follow TikTok's order as served. **Pricing is metered at 25 credits per board plus 1 credit per video returned** (20 videos = 45 credits), because each read of the board has a fixed cost. An empty board costs nothing.", "tags": [ "tiktok" ], "operationId": "get_tiktok_videos_popular", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 26, "x-credit-cost-min": 26, "x-credit-cost-max": 45, "x-credit-cost-formula": "25 credits per board plus 1 credit per video returned. The default limit of 20 holds 45 credits and settles to the videos actually returned; an empty board costs nothing.", "parameters": [ { "name": "countryCode", "in": "query", "required": false, "description": "Market: US, JP, VN, TH or ID, the only markets TikTok publishes this board for. Defaults to US.", "schema": { "type": "string", "enum": [ "US", "JP", "VN", "TH", "ID" ] }, "example": "US" }, { "name": "period", "in": "query", "required": false, "description": "Window in days: 7 or 30. Defaults to 7.", "schema": { "type": "string", "enum": [ "7", "30" ] }, "example": "7" }, { "name": "orderBy", "in": "query", "required": false, "description": "How TikTok ranks the board: views (the default), engagement, or six_second_views.", "schema": { "type": "string", "enum": [ "views", "engagement", "six_second_views" ] }, "example": "views" }, { "name": "limit", "in": "query", "required": false, "description": "How many videos to return, 1-20, default 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 20 } }, { "name": "since", "in": "query", "required": false, "description": "Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.", "schema": { "type": "string" } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/videos/popular" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical post wrappers ({ post, computed })", "items": { "type": "object", "description": "Canonical post wrapper", "properties": { "post": { "type": "object", "description": "Canonical Post object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "integer", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "integer", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "integer", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "integer", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "integer", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "integer", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "string", "null" ], "description": "Leaf at computed.labels" }, "labels_evidence": { "type": [ "string", "null" ], "description": "Leaf at computed.labels_evidence" } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/videos/popular", "data": { "items": [ { "post": { "id": "7637623185378200845", "url": "https://www.tiktok.com/@linguamarina/video/7637623185378200845", "content": { "text": "PDFs in 2016: you send a file. PDFs in 2026: you send an experience. #AdobeAcrobatPartner", "media_urls": "https://v16m-default.tiktokcdn-us.com/ffcc07a41d17debbb4370d167d69be97/6aa64689/video/tos/useast5/tos-useast5-pve-0068-tx/oguJeAponvOogH25FxWQAOM1RfAGJfRRgf8cIJ/", "thumbnail_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/o8GJOFO5A6efHrf6dnvAAkIe7AIRQAwIDJSMEA~tplv-photomode-zoomcover-tcm:720:720.jpeg", "duration_seconds": null }, "author": { "username": "linguamarina", "display_name": "Silicon Valley Girl", "avatar_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/57f759b02de679189cf842ebf9341aa7~tplv-tiktokx-cropcenter:300:300.jpeg", "verified": null }, "engagement": { "views": 153672528, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-05-08T20:38:56.000Z", "ext": { "author_id": "6844415658239721478", "author_followers": 3007554, "trend": { "rank": 1, "country_code": "US", "period_days": 7, "order_by": "views", "period_views": 62318158, "organic_views": 9531351, "engagement_rate": 0.001632878815192195, "six_second_view_through_rate": 0.02756890176226899, "content_tags": [] } } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": 184407034 } }, { "post": { "id": "7680228073656093966", "url": "https://www.tiktok.com/@iamcardib/video/7680228073656093966", "content": { "text": "Y’all know I don’t play about my @Chipotle! The official Bardi Bowl + the new Chili Lime Chips are officially in the Chipotle app. Get into it!!!!!", "media_urls": "https://v16m-default.tiktokcdn-us.com/7414aae302c9b68da8a6ab51b6fc7c5f/6aa646b8/video/tos/useast5/tos-useast5-ve-0068c004-tx/osZVRauhqISWETDepBlFk2aEEwDQ9qAOAgfVx8/", "thumbnail_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/oowVAZglfAE8caCaBDRq8tBupEDSFEmO9a5I3e~tplv-photomode-zoomcover-tcm:720:720.jpeg", "duration_seconds": null }, "author": { "username": "iamcardib", "display_name": "Cardi B", "avatar_url": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/dcd32ba414395bcdd66310eea46e9625~tplv-tiktokx-cropcenter:300:300.jpeg", "verified": null }, "engagement": { "views": 131166904, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-08-31T16:07:59.000Z", "ext": { "author_id": "7506219246691729454", "author_followers": 36236761, "trend": { "rank": 2, "country_code": "US", "period_days": 7, "order_by": "views", "period_views": 54048688, "organic_views": 16137343, "engagement_rate": 0.008164120468567156, "six_second_view_through_rate": 0.07433548136286997, "content_tags": [] } } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": 157400285 } } ], "total": null }, "credits_used": 27, "credits_remaining": 9973, "request_id": "req-a1b2c3d4e5f6" } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/profile/region": { "get": { "summary": "Get TikTok profile region", "description": "Returns the ISO 3166-1 alpha-2 region code for a public TikTok profile (e.g. `US` for United States, `MX` for Mexico), together with the account's follower, following, post and like counts, display name, avatar, bio and verified flag. Useful for routing region-locked workflows and deduplicating profiles by country. The counters are filled from a second source inside the same request, for the same one credit, so you do not need a separate profile call to get them. The region itself is the one leaf that can be absent: it comes from a single source, and if that source is unavailable the rest of the profile is still returned with `location` null.", "tags": [ "tiktok" ], "operationId": "get_tiktok_profile_region", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "TikTok username without the @ symbol", "schema": { "type": "string" }, "example": "stoolpresidente" }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/profile/region" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "id": { "type": "string", "description": "Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)" }, "username": { "type": [ "string", "null" ], "description": "User handle or username" }, "display_name": { "type": [ "string", "null" ], "description": "Display name or full name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to profile picture" }, "bio": { "type": [ "string", "null" ], "description": "Profile biography or description" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the account is verified" }, "followers": { "type": [ "integer", "null" ], "description": "Follower or subscriber count as an integer. Exact on Instagram and on TikTok when the source exposes an unrounded figure. YouTube above 1,000 subscribers is YouTube's published three-significant-figure figure. When the integer is a published/rounded value, `author.ext.followers_approximate` is true." }, "following": { "type": [ "integer", "null" ], "description": "Number of accounts followed" }, "posts_count": { "type": [ "integer", "null" ], "description": "Total number of posts / videos / tracks / episodes" }, "likes_count": { "type": [ "integer", "null" ], "description": "Total likes received across the author's content (when surfaced)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the profile page" }, "location": { "type": [ "string", "null" ], "description": "ISO region code (e.g. `US`) or freeform location string when surfaced" }, "external_url": { "type": [ "string", "null" ], "description": "Bio link / external website URL when surfaced by the platform" }, "private": { "type": [ "boolean", "null" ], "description": "Boolean at author.private" }, "joined_at": { "type": [ "string", "null" ], "description": "String at author.joined_at" }, "last_post_at": { "type": [ "string", "null" ], "description": "String at author.last_post_at" }, "ext": { "type": [ "object", "null" ], "description": "Nested object: author.ext", "properties": { "social_context": { "type": [ "string", "null" ], "description": "String at author.ext.social_context" }, "account_created": { "type": [ "string", "null" ], "description": "String at author.ext.account_created" }, "country": { "type": [ "string", "null" ], "description": "String at author.ext.country" }, "country_name": { "type": [ "string", "null" ], "description": "String at author.ext.country_name" }, "collects_received": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.collects_received" }, "former_usernames": { "type": [ "array", "null" ], "description": "Array at author.ext.former_usernames", "items": { "type": "string", "description": "String at author.ext.former_usernames" } }, "former_usernames_count": { "type": [ "integer", "null" ], "description": "Instagram profile/about: how many former usernames Instagram's \"About this account\" panel lists for the account. 0 when the panel lists none, null when the panel could not be read on this call (the response then carries a note saying so). A count above 0 means the handle was renamed at least once; the names themselves are not published." }, "verified_at": { "type": [ "string", "null" ], "description": "Instagram profile/about, opt-in (`include=verified_at`): the month Instagram verified the account, as the panel shows it (\"April 2024\"). A month, not a date. Null when the account is not verified or the panel shows no verification date. Absent unless requested." }, "public_email": { "type": [ "string", "null" ], "description": "String at author.ext.public_email" }, "contact_email": { "type": [ "string", "null" ], "description": "Opt-in (`contact_email=1` on instagram/profile, youtube/channel and youtube/channel/about). When the bio lists two or more email addresses, the one the creator gives for contacting them personally, copied verbatim. Null when there is one address or none, when every address belongs to a manager, agency or brand, or when the choice was not confident. `author.ext.public_email` (the first address in the bio) is unchanged." }, "public_phone": { "type": [ "string", "null" ], "description": "String at author.ext.public_phone" }, "similar_source": { "type": [ "string", "null" ], "description": "String at author.ext.similar_source" }, "instagram_username": { "type": [ "string", "null" ], "description": "String at author.ext.instagram_username" }, "similar_via": { "type": [ "string", "null" ], "description": "String at author.ext.similar_via" }, "business_category": { "type": [ "string", "null" ], "description": "String at author.ext.business_category" }, "bio_links": { "type": [ "array", "null" ], "description": "Array at author.ext.bio_links", "items": { "type": "object", "description": "Nested object: author.ext.bio_links", "properties": { "title": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.title" }, "url": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.url" }, "link_type": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.link_type" } } } }, "is_business": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_business" }, "is_professional": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_professional" }, "creator_marketplace": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.creator_marketplace" }, "verification_label": { "type": [ "string", "null" ], "description": "String at author.ext.verification_label" }, "fbid": { "type": [ "string", "null" ], "description": "String at author.ext.fbid" }, "hd_avatar_url": { "type": [ "string", "null" ], "description": "String at author.ext.hd_avatar_url" }, "website": { "type": [ "string", "null" ], "description": "String at author.ext.website" }, "cover_url": { "type": [ "string", "null" ], "description": "String at author.ext.cover_url" }, "page_active": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.page_active" }, "employee_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.employee_count" }, "employee_count_range": { "type": [ "object", "null" ], "description": "Nested object: author.ext.employee_count_range", "properties": { "start": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.employee_count_range.start" }, "end": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.employee_count_range.end" } } }, "founded_year": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.founded_year" }, "company_type": { "type": [ "string", "null" ], "description": "String at author.ext.company_type" }, "tagline": { "type": [ "string", "null" ], "description": "String at author.ext.tagline" }, "specialities": { "type": [ "array", "null" ], "description": "Array at author.ext.specialities", "items": { "type": "string", "description": "String at author.ext.specialities" } }, "industries": { "type": [ "array", "null" ], "description": "Array at author.ext.industries", "items": { "type": "string", "description": "String at author.ext.industries" } }, "headquarters": { "type": [ "string", "null" ], "description": "Leaf at author.ext.headquarters" }, "locations": { "type": [ "array", "null" ], "description": "Array at author.ext.locations", "items": { "type": "string", "description": "Leaf at author.ext.locations" } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at author.ext.hashtags", "items": { "type": "string", "description": "Leaf at author.ext.hashtags" } }, "funding": { "type": [ "string", "null" ], "description": "Leaf at author.ext.funding" }, "address": { "type": [ "string", "null" ], "description": "String at author.ext.address" }, "price_range": { "type": [ "string", "null" ], "description": "String at author.ext.price_range" }, "rating": { "type": [ "string", "null" ], "description": "String at author.ext.rating" }, "rating_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.rating_count" }, "talking_about_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.talking_about_count" }, "business_hours": { "type": [ "array", "null" ], "description": "Array at author.ext.business_hours", "items": { "type": "string", "description": "Leaf at author.ext.business_hours" } }, "links": { "type": [ "array", "null" ], "description": "Array at author.ext.links", "items": { "type": "string", "description": "Leaf at author.ext.links" } }, "ad_library_page_id": { "type": [ "string", "null" ], "description": "String at author.ext.ad_library_page_id" }, "ad_library_status": { "type": [ "string", "null" ], "description": "String at author.ext.ad_library_status" }, "urn": { "type": [ "string", "null" ], "description": "String at author.ext.urn" }, "is_top_voice": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_top_voice" }, "is_premium": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_premium" }, "is_creator": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_creator" }, "is_influencer": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_influencer" }, "is_open_to_work": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_open_to_work" }, "is_hiring": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_hiring" }, "member_id": { "type": [ "string", "null" ], "description": "String at author.ext.member_id" }, "company_id": { "type": [ "string", "null" ], "description": "String at author.ext.company_id" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at author.ext.reaction_type" }, "followers_approximate": { "type": [ "boolean", "null" ], "description": "True when `author.followers` is a published or rounded figure rather than an unrounded census: LinkedIn people-list display buckets, TikTok `stats.followerCount` when the exact sibling is absent, and YouTube subscriber counts at or above 1,000. Null or absent on exact counts." }, "counts_source": { "type": [ "string", "null" ], "description": "TikTok profile only. Which of TikTok's two live counter sets `author.followers`, `author.following`, `author.likes_count` and `author.posts_count` carry: `app` (TikTok's app counters, the default) or `web` (the website's `statsV2`, returned with `counts=web`). The two sets can differ by a few percent in either direction." }, "keywords": { "type": [ "string", "null" ], "description": "String at author.ext.keywords" }, "total_views": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.total_views" }, "joined_at_timestamp": { "type": [ "string", "null" ], "description": "String at author.ext.joined_at_timestamp" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at author.ext.topicCategories", "items": { "type": "string", "description": "String at author.ext.topicCategories" } }, "bannerExternalUrl": { "type": [ "string", "null" ], "description": "String at author.ext.bannerExternalUrl" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.madeForKids" }, "hiddenSubscriberCount": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.hiddenSubscriberCount" }, "related_playlists": { "type": [ "string", "null" ], "description": "Leaf at author.ext.related_playlists" }, "topic_ids": { "type": [ "array", "null" ], "description": "Array at author.ext.topic_ids", "items": { "type": "string", "description": "String at author.ext.topic_ids" } }, "unsubscribed_trailer": { "type": [ "string", "null" ], "description": "String at author.ext.unsubscribed_trailer" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at author.ext.localizations" }, "monthly_listeners": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.monthly_listeners" }, "total_ratings": { "type": [ "integer", "null" ], "description": "Spotify podcasts only: how many listeners have rated the show. Cumulative over the show's whole run, so it reflects longevity as well as size, and it is NOT an audience count (Spotify publishes no play, download, subscriber or follower count for a podcast)" }, "average_rating": { "type": [ "integer", "null" ], "description": "Spotify podcasts only: mean listener rating from 0 to 5. Fractional (e.g. 4.66) despite the integer type this schema emits for every numeric leaf" }, "creator_username": { "type": [ "string", "null" ], "description": "String at author.ext.creator_username" }, "join_policy": { "type": [ "string", "null" ], "description": "String at author.ext.join_policy" }, "is_nsfw": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_nsfw" }, "rules": { "type": [ "array", "null" ], "description": "Array at author.ext.rules", "items": { "type": "string", "description": "Leaf at author.ext.rules" } }, "weekly_active_users": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.weekly_active_users" }, "weekly_contributions": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.weekly_contributions" }, "rules_text": { "type": [ "string", "null" ], "description": "String at author.ext.rules_text" }, "language": { "type": [ "string", "null" ], "description": "String at author.ext.language" }, "post_karma": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.post_karma" }, "comment_karma": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.comment_karma" }, "awardee_karma": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.awardee_karma" }, "trophy_count": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.trophy_count" }, "banner_url": { "type": [ "string", "null" ], "description": "String at author.ext.banner_url" }, "profile_title": { "type": [ "string", "null" ], "description": "String at author.ext.profile_title" }, "social_links": { "type": [ "array", "null" ], "description": "Array at author.ext.social_links", "items": { "type": "string", "description": "Leaf at author.ext.social_links" } }, "bio_link": { "type": [ "string", "null" ], "description": "String at author.ext.bio_link" }, "embed_html": { "type": [ "string", "null" ], "description": "String at author.ext.embed_html" }, "embed_url": { "type": [ "string", "null" ], "description": "String at author.ext.embed_url" }, "group": { "type": [ "string", "null" ], "description": "Leaf at author.ext.group" }, "search_hit": { "type": [ "object", "null" ], "description": "Nested object: author.ext.search_hit", "properties": { "match": { "type": [ "string", "null" ], "description": "Leaf at author.ext.search_hit.match" }, "title": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.title" }, "snippet": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.snippet" }, "evidence_url": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.evidence_url" }, "matched_urls": { "type": [ "array", "null" ], "description": "Array at author.ext.search_hit.matched_urls", "items": { "type": "string", "description": "String at author.ext.search_hit.matched_urls" } } } }, "blog_name": { "type": [ "string", "null" ], "description": "String at author.ext.blog_name" }, "blog_no": { "type": [ "string", "null" ], "description": "String at author.ext.blog_no" }, "visitors_today": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.visitors_today" }, "visitors_total": { "type": [ "integer", "null" ], "description": "Numeric at author.ext.visitors_total" }, "topic": { "type": [ "string", "null" ], "description": "String at author.ext.topic" }, "power_blog": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.power_blog" }, "official_blog": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.official_blog" } } }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } } }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/profile/region", "data": { "author": { "id": "stoolpresidente", "username": "stoolpresidente", "display_name": "Dave Portnoy", "avatar_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/7310178711609032710~tplv-tiktokx-cropcenter:1080:1080.webp?dr=10399&refresh_token=945682bc&x-expires=1791126000&x-signature=rcFPX21DyPIX7gvMCEZQcAdD%2FQM%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=2472a6c6&idc=no1a", "bio": "El Presidente/Barstool Sports Founder.", "verified": true, "followers": 4784231, "following": 96, "posts_count": 2535, "likes_count": 230737178, "url": "https://www.tiktok.com/@stoolpresidente", "location": "US" }, "computed": { "engagement_rate": null, "language": null, "content_category": null, "estimated_reach": null } }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T15:40:23.298Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/adlibrary/search": { "get": { "summary": "Search the TikTok Ad Library", "description": "Returns ads from the TikTok Ad Library (the EU Commercial Content Library) matching a keyword or advertiser name, 12 per page. Each ad carries the creative video, the title, the advertiser name, the impression estimate at `engagement.views`, the spend band, the first-shown date and the audit status. The search row publishes no brand, landing page, advertiser account or avatar, so on a plain call `post.ext.ad.brand_name`, `post.ext.ad.landing_page`, `post.ext.ad.profile_web_link` and `post.author.avatar_url` are null on every row. Send `include=ad` and every row is joined, in the same call, to the per-ad lookup that carries them: the registered brand name, the landing page, the advertiser's TikTok profile link and avatar, and where the library has them the campaign objectives, the countries the ad ran in and the ad source. Cost: 5 credits for the page plus 1 credit per ad filled from a fresh lookup (12 ads, so 17 at most); ads already in cache are filled for free, ads that could not be filled are refunded, and a repeat within the cache window is 0. Time: a plain call is 4 to 19 seconds; `include=ad` adds 5 to 20 seconds on a fresh page (the lookups run in parallel and the call waits for the slowest, never more than 20 seconds) and nothing when the ads are already cached. `limit=N` (1 to 12) takes the top N ads and, with `include`, caps the extra credits at N. The response carries a `hydration` block itemising rows, lookups, cache hits, credits and milliseconds. Like, comment and share counts are not published by the library on either call. Page with cursor.", "tags": [ "tiktok" ], "operationId": "get_tiktok_adlibrary_search", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "x-credit-cost-min": 5, "x-credit-cost-max": 17, "x-credit-cost-formula": "5 credits for the page. include=ad holds 1 credit per ad, at most 12 (or `limit`), and keeps only the ads filled from a fresh lookup, so a page is at most 17 credits; ads served from cache are free, unfilled ads are refunded, and a repeat within the cache window costs 0. The page is cached for 2 minutes and the per-ad lookups for 30 minutes. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total.", "x-socialcrawl-oneOf": [ [ "query", "advertiser_name" ] ], "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Keyword or phrase to search the TikTok Ad Library. (one of: query, advertiser_name; at least one required)", "schema": { "type": "string" } }, { "name": "advertiser_name", "in": "query", "required": false, "description": "Advertiser name as it appears in the TikTok Ad Library. (one of: query, advertiser_name; at least one required)", "schema": { "type": "string" }, "example": "Gymshark" }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from the previous response to fetch the next page.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Set to `ad` (one token only) to fill the registered brand name, the landing page, the advertiser's TikTok profile link and avatar (`post.ext.ad.brand_name`, `post.ext.ad.landing_page`, `post.ext.ad.profile_web_link`, `post.author.avatar_url`), plus the objectives, countries and source where the library has them, on every ad in this one call. Holds 1 credit per ad (at most 12, or `limit`) and keeps only the ads filled from a fresh lookup; ads already in cache and ads that could not be filled are refunded, so the most a call can cost is 5 + ads. Adds 5 to 20 seconds on a fresh page (never more than 20) and nothing when the ads are already cached; read `data.hydration` for the rows, the credits held and kept, and the time.", "schema": { "type": "string", "enum": [ "ad" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Take the top N ads of the page (1 to 12) after the search has run. With `include=ad` it also caps the extra credits at N: `limit=3&include=ad` costs at most 8. It is not a page size: `next_cursor` still advances past the full page.", "schema": { "type": "integer", "minimum": 1, "maximum": 12 } }, { "name": "since", "in": "query", "required": false, "description": "Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.", "schema": { "type": "string" } }, { "name": "max_pages", "in": "query", "required": false, "description": "1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "max_items", "in": "query", "required": false, "description": "1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: \"max_items\"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`\"time_budget\"`): send the returned cursor with the same params to continue.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "max_credits", "in": "query", "required": false, "description": "1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: \"max_credits\"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/adlibrary/search" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical post wrappers ({ post, computed })", "items": { "type": "object", "description": "Canonical post wrapper", "properties": { "post": { "type": "object", "description": "Canonical Post object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "integer", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "integer", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "integer", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "integer", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "integer", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "integer", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "string", "null" ], "description": "Leaf at computed.labels" }, "labels_evidence": { "type": [ "string", "null" ], "description": "Leaf at computed.labels_evidence" } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/adlibrary/search", "data": { "items": [ { "post": { "id": "1875950426759393", "url": "https://library.tiktok.com/ads/detail/?id=1875950426759393", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://library.tiktok.com/api/v1/cdn/1790955602/video/aHR0cHM6Ly92MTZtLnRpa3Rva2Nkbi5jb20vMWNkMTQyZGE4NjdiOTY3MTg5ZDdhMmI3NjA2NzdlZWUvNmFjMDI0YzUvdmlkZW8vdG9zL3VzZWFzdDJhL3Rvcy11c2Vhc3QyYS12ZS0wMDUxYzc5OS1ldXR0cC9va2VHQWU5M3RBMGJHZm1ROFlpSUFiQ2dvREdMZ083UFRLSEFiSS8=/333cccf1-d443-43a9-a1d4-1425ef2e0065?a=475769&bt=407&btag=e000b8000&bti=PDU2NmYwMy86&ft=.NpOcInz7ThBcg4GXq8Zmo&l=20261002234001F7F79306A9DDC59CA559&mime_type=video_mp4&rc=ZDo5ODNmZTk5PGZmOzM3Z0BpajQ0cWw5cmlvZDMzODYzNEBeNi0uL140XjExLjQuMC01YSNyXjMxMmRzamRhLS1kMDFzcw%3D%3D&signature=pySkbA6%2BOo%2B3IlSi9BfHkSY3G4z6mkdE84P1DKhY1HI%3D&vvpl=1", "thumbnail_url": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o4QGNFTAeCVlDsDEQfPtfgJAEj6HAGxtW2jAbP~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=99818dc9&x-expires=1790974800&x-signature=2VA8dpjOqeVdK0Oww0jlZzx5X50%3D&t=4d5b0474&ps=13740610&shp=0c75dd76&shcp=9b759fb9&idc=sg1", "duration_seconds": null }, "author": { "username": "user_4c69b3", "display_name": "user_4c69b3", "avatar_url": null, "verified": false }, "engagement": { "views": 0, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-10T00:00:00.000Z", "ext": { "published_at_epoch": 1788998400000, "ad": { "estimated_audience": "10K-100K", "spent": "", "audit_status": "1", "last_shown_date": 1790812800000, "type": "2", "image_urls": [ "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o4QGNFTAeCVlDsDEQfPtfgJAEj6HAGxtW2jAbP~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=99818dc9&x-expires=1790974800&x-signature=2VA8dpjOqeVdK0Oww0jlZzx5X50%3D&t=4d5b0474&ps=13740610&shp=0c75dd76&shcp=9b759fb9&idc=sg1" ] } } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": null } }, { "post": { "id": "1876714855831730", "url": "https://library.tiktok.com/ads/detail/?id=1876714855831730", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://library.tiktok.com/api/v1/cdn/1790955602/video/aHR0cHM6Ly92MTZtLnRpa3Rva2Nkbi5jb20vYmMyMmQ0ZTgwNDI5YzFhMDZkOTg0OWFmYWNlMTZjZjIvNmFjMDI0YmEvdmlkZW8vdG9zL3VzZWFzdDJhL3Rvcy11c2Vhc3QyYS12ZS0wMDUxYzc5OS1ldXR0cC9vb3REUERHYUw1ZXZRQkFmeWJCOEFDb0dSVzVRSWdOZUFWQWpuSS8=/4c3fe79c-7078-4303-83b3-0726d3849a56?a=475769&bt=404&btag=e000b0000&bti=PDU2NmYwMy86&ft=.NpOcInz7ThBcg4GXq8Zmo&l=20261002234001F7F79306A9DDC59CA559&mime_type=video_mp4&rc=NGlpZTlmaDozN2dmOzRmaEBpM2lwPHg5cjxtZDMzODYzNEBfLV9gNTMtXjAxMDU2LTAvYSM1XnAxMmRzYWphLS1kMDFzcw%3D%3D&signature=edmEXPofilLjTAKwYN%2F4ntcJopyPfqPub6ml2xVjZxg%3D&vvpl=1", "thumbnail_url": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o8AGjQASRLoeACgq5VWvbKAyPIEoeDeGIgAg8X~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=7a1dd5b2&x-expires=1790974800&x-signature=2n8ko9XNFXPS8JzuncGtZaKeyig%3D&t=4d5b0474&ps=13740610&shp=0c75dd76&shcp=9b759fb9&idc=sg1", "duration_seconds": null }, "author": { "username": "user_4c69b3", "display_name": "user_4c69b3", "avatar_url": null, "verified": false }, "engagement": { "views": 0, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-19T00:00:00.000Z", "ext": { "published_at_epoch": 1789776000000, "ad": { "estimated_audience": "0-1K", "spent": "", "audit_status": "1", "last_shown_date": 1790812800000, "type": "2", "image_urls": [ "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o8AGjQASRLoeACgq5VWvbKAyPIEoeDeGIgAg8X~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=7a1dd5b2&x-expires=1790974800&x-signature=2n8ko9XNFXPS8JzuncGtZaKeyig%3D&t=4d5b0474&ps=13740610&shp=0c75dd76&shcp=9b759fb9&idc=sg1" ] } } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": null } } ], "next_cursor": "eyJvZmZzZXQiOjEyLCJzZWFyY2hfaWQiOiJleUpzWVhOMFgzTnZjblFpT2xzeE56a3dPREV5T0RBd01EQXdYU3dpYm1WNGRGOWpkWEp6YjNJaU9qRXlmUT09In0", "total": 41533, "dropped": 0 }, "credits_used": 5, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiZXlKdlptWnpaWFFpT2pFeUxDSnpaV0Z5WTJoZmFXUWlPaUpsZVVweldWaE9NRmd6VG5aamJsRnBUMnh6ZUU1NmEzZFBSRVY1VDBSQmQwMUVRWGRZVTNkcFltMVdOR1JHT1dwa1dFcDZZak5KYVU5cVJYbG1VVDA5SW4wIiwiZSI6InRpa3Rvay9hZGxpYnJhcnkvc2VhcmNoIiwicCI6ImN1cnNvciJ9", "has_more": true, "page_size": 2 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T15:40:00.806Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/adlibrary/ad": { "get": { "summary": "Get a TikTok Ad Library ad", "description": "Returns one ad from the TikTok Ad Library: creative video, title, advertiser TikTok account, landing page, brand name, and first-shown date. Pass ad_id or a library.tiktok.com URL.", "tags": [ "tiktok" ], "operationId": "get_tiktok_adlibrary_ad", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "x-socialcrawl-oneOf": [ [ "ad_id", "url" ] ], "parameters": [ { "name": "ad_id", "in": "query", "required": false, "description": "TikTok Ad Library ad id, or a library.tiktok.com ads/detail URL. (one of: ad_id, url; at least one required)", "schema": { "type": "string" }, "example": "1869335220395266" }, { "name": "url", "in": "query", "required": false, "description": "TikTok Ad Library ads/detail URL. (one of: ad_id, url; at least one required)", "schema": { "type": "string" } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/adlibrary/ad" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } } }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached" ] }, "example": { "success": true, "platform": "youtube", "endpoint": "/v1/youtube/video", "data": { "post": { "id": "dQw4w9WgXcQ", "content": { "text": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)", "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg", "duration_seconds": 214, "media_urls": "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw" }, "author": { "username": "UCuAXFkgsw1L7xaCfnd5JJOw", "display_name": "Rick Astley", "avatar_url": null, "verified": null }, "engagement": { "views": 1789065639, "likes": 19216844, "comments": 2443809, "shares": null, "saves": null }, "published_at": "2009-10-25T06:57:33Z", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "ext": { "content_type": "video", "tags": [ "rick astley", "Never Gonna Give You Up", "nggyu", "never gonna give you up lyrics", "rick rolled", "Rick Roll", "rick astley official", "rickrolled", "Fortnite song", "Fortnite event", "Fortnite dance", "fortnite never gonna give you up", "rick roll", "rickrolling", "rick rolling", "never gonna give you up", "80s music", "rick astley new", "animated video", "rickroll", "meme songs", "never gonna give u up lyrics", "Rick Astley 2022", "never gonna let you down", "animated", "rick rolls 2022", "never gonna give you up karaoke" ], "categoryId": "10", "categoryTitle": "Music", "topicCategories": [ "https://en.wikipedia.org/wiki/Electronic_music", "https://en.wikipedia.org/wiki/Music", "https://en.wikipedia.org/wiki/Pop_music", "https://en.wikipedia.org/wiki/Rhythm_and_blues", "https://en.wikipedia.org/wiki/Soul_music" ], "duration": "PT3M34S", "license": "youtube", "madeForKids": false, "defaultAudioLanguage": "en", "hasPaidProductPlacement": false, "caption": "true", "description": "The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100. It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”. The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2. The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo", "default_language": "en" }, "flags": { "deleted": false, "nsfw": null, "spoiler": null, "pinned": null } }, "computed": { "engagement_rate": 0.012107, "language": "en", "content_category": "entertainment", "estimated_reach": 2146878767 } }, "credits_used": 1, "credits_remaining": 9999, "request_id": "req-8Kq2ZmR4vT9xLb3P", "cached": false, "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/search/suggestions": { "get": { "summary": "Get TikTok search suggestions", "description": "Returns TikTok's search autocomplete suggestions for a partial query, the same terms the search box shows. Useful for keyword expansion before search or search/top.", "tags": [ "tiktok" ], "operationId": "get_tiktok_search_suggestions", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Partial search query to autocomplete.", "schema": { "type": "string" }, "example": "dogs" }, { "name": "region", "in": "query", "required": false, "description": "ISO 3166-1 alpha-2 country code to localize suggestions.", "schema": { "type": "string" } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/search/suggestions" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of search result objects", "items": { "type": "object", "description": "Search result item" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/search/suggestions", "data": { "items": [ { "text": "dogs", "position": 0, "language": "en", "score": 0.0133961765 }, { "text": "dogs xxl zoo", "position": 1, "language": "en", "score": 0.02936133 } ], "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": null, "has_more": false, "page_size": 10 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T12:51:31.276Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/collection/videos": { "get": { "summary": "List videos in a TikTok collection", "description": "Returns the public videos inside a TikTok collection. Each video includes caption, play/like/comment/share/save counts, author, and a playable URL. Page with max_cursor.", "tags": [ "tiktok" ], "operationId": "get_tiktok_collection_videos", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full URL of the TikTok collection.", "schema": { "type": "string" }, "example": "https://www.tiktok.com/@kibblemaster808/collection/Want-to-go-7665668414573546258" }, { "name": "max_cursor", "in": "query", "required": false, "description": "Cursor from the previous response to fetch the next page of collection videos. Native upstream cursor param. Send the universal `cursor` instead: the API maps it to this name for you.", "deprecated": true, "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.", "schema": { "type": "string" } }, { "name": "max_pages", "in": "query", "required": false, "description": "1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "max_items", "in": "query", "required": false, "description": "1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: \"max_items\"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`\"time_budget\"`): send the returned cursor with the same params to continue.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "max_credits", "in": "query", "required": false, "description": "1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: \"max_credits\"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "cursor", "in": "query", "required": false, "description": "Universal pagination cursor. Send `pagination.next_cursor` from the previous response back verbatim: the API maps it to this endpoint's native `max_cursor` (cursor style). You never construct, decode, or look up a cursor. Omit it for page 1.", "schema": { "type": "string" } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/collection/videos" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical post wrappers ({ post, computed })", "items": { "type": "object", "description": "Canonical post wrapper", "properties": { "post": { "type": "object", "description": "Canonical Post object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "integer", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "integer", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "integer", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "integer", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "integer", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "integer", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "string", "null" ], "description": "Leaf at computed.labels" }, "labels_evidence": { "type": [ "string", "null" ], "description": "Leaf at computed.labels_evidence" } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/collection/videos", "data": { "items": [ { "post": { "id": "7663018809392909588", "url": "https://www.tiktok.com/@user_112662/video/7663018809392909588", "content": { "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "media_urls": "https://v16-webapp-prime.us.tiktok.com/video/tos/alisg/tos-alisg-pve-0037c001/o0qLUVxZ5BXQIAFRqBTIOi5gGWEzgff66KBDEO/?a=1988&bti=ODszNWYuMDE6&&bt=371&ft=aEeq8qT0mIoPD12xrWMI3wUV3OAbMeF~O5&mime_type=video_mp4&rc=N2U1Mzs7ZjszN2Q1MzxpZEBpamU5PG85cmg7PDMzODczNEBgYWEwYV8vXzUxMzMzLjFjYSNnZ28zMmRjMmBhLS1kMTFzcw%3D%3D&expire=1791098925&l=2026100207273705887C36FF5722B952EA&ply_type=2&policy=2&signature=54adf6ebc7e24a6539c8e9ead6fcc3fa&tk=tt_chain_token&btag=e00090000", "thumbnail_url": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/oUYM7iBIKB1BL5CGgwAtAiwJEfLCFXAiX9IAEA~tplv-tiktokx-origin.image?dr=9636&x-expires=1791097200&x-signature=%2F0sQMztJdQlJTo7So4grolBCjUA%3D&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast5", "duration_seconds": 68 }, "author": { "username": "user_112662", "display_name": "user_112662", "avatar_url": "https://example.com/avatars/user_8a1e97.png", "verified": false }, "engagement": { "views": 1000000, "likes": 132500, "comments": 424, "shares": 18800, "saves": 22000 }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-07-16T07:06:47.000Z", "ext": { "author_id": "user_ee7531", "published_at_epoch": 1784185607 } }, "computed": { "engagement_rate": 0.151724, "language": "en", "content_category": "lifestyle", "estimated_reach": 1200000 } }, { "post": { "id": "7664493425168747796", "url": "https://www.tiktok.com/@user_112662/video/7664493425168747796", "content": { "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "media_urls": "https://v16-webapp-prime.us.tiktok.com/video/tos/alisg/tos-alisg-pve-0037c001/oENuoINEGeP03CwgAIeEAgQ7OLv9CUDIgpfjYd/?a=1988&bti=ODszNWYuMDE6&&bt=327&ft=aEeq8qT0mIoPD12xrWMI3wUV3OAbMeF~O5&mime_type=video_mp4&rc=NGdkZTk3M2Q5ZDlmOTZmOkBpamp2eXQ5cjR1PDMzODczNEA2L18yNS5fNmMxXjJfL2FfYSNjYm9hMmRrcWJhLS1kMTFzcw%3D%3D&expire=1791098930&l=2026100207273705887C36FF5722B952EA&ply_type=2&policy=2&signature=3a082b7e156721fb4ede8deb7af0a359&tk=tt_chain_token&btag=e000d0000", "thumbnail_url": "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/okAADIGUoQpAAjTQBe78EWguCMWjS4IeBeQQFA~tplv-tiktokx-origin.image?dr=9636&x-expires=1791097200&x-signature=s4hvqqmijyjMtrUWQej3BwlOyDk%3D&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast5", "duration_seconds": 73 }, "author": { "username": "user_112662", "display_name": "user_112662", "avatar_url": "https://example.com/avatars/user_8a1e97.png", "verified": false }, "engagement": { "views": 26500, "likes": 3078, "comments": 10, "shares": 343, "saves": 1251 }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-07-20T06:29:10.000Z", "ext": { "author_id": "user_ee7531", "published_at_epoch": 1784528950 } }, "computed": { "engagement_rate": 0.129472, "language": "en", "content_category": "other", "estimated_reach": 31800 } } ], "total": null, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": null, "has_more": false, "page_size": 5 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T07:27:38.166Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/profile/playlists": { "get": { "summary": "List a TikTok account's playlists", "description": "Returns the playlists a TikTok creator has published on their profile, each with its playlist id, name, and the number of videos it contains under `post.ext.video_count`. Pass the playlist id to `/v1/tiktok/playlist/videos` to read the videos themselves. The video count is the account's own figure and is accurate; view totals are not exposed for a playlist, so `post.engagement` is null on every row.", "tags": [ "tiktok" ], "operationId": "get_tiktok_profile_playlists", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-socialcrawl-oneOf": [ [ "handle", "user_id" ] ], "parameters": [ { "name": "handle", "in": "query", "required": false, "description": "TikTok username without the @ symbol. (one of: handle, user_id; at least one required)", "schema": { "type": "string" }, "example": "chipotle" }, { "name": "user_id", "in": "query", "required": false, "description": "TikTok numeric user ID. Use this for faster responses. (one of: handle, user_id; at least one required)", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.", "schema": { "type": "string" } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/profile/playlists" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical post wrappers ({ post, computed })", "items": { "type": "object", "description": "Canonical post wrapper", "properties": { "post": { "type": "object", "description": "Canonical Post object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "integer", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "integer", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "integer", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "integer", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "integer", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "integer", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "string", "null" ], "description": "Leaf at computed.labels" }, "labels_evidence": { "type": [ "string", "null" ], "description": "Leaf at computed.labels_evidence" } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/profile/playlists", "data": { "items": [ { "post": { "id": "7229371484127382314", "url": null, "content": { "text": "Sample comment text (redacted).", "media_urls": null, "thumbnail_url": null, "duration_seconds": null }, "author": { "username": null, "display_name": null, "avatar_url": null, "verified": false }, "engagement": { "views": null, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": null, "ext": { "video_count": 3 } }, "computed": { "engagement_rate": null, "language": null, "content_category": "other", "estimated_reach": null } }, { "post": { "id": "7060939594908453679", "url": null, "content": { "text": "Sample comment text (redacted).", "media_urls": null, "thumbnail_url": null, "duration_seconds": null }, "author": { "username": null, "display_name": null, "avatar_url": null, "verified": false }, "engagement": { "views": null, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": null, "ext": { "video_count": 3 } }, "computed": { "engagement_rate": null, "language": null, "content_category": null, "estimated_reach": null } } ], "total": null, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": null, "has_more": false, "page_size": 6 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T13:11:26.174Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/playlist/videos": { "get": { "summary": "List videos in a TikTok playlist", "description": "Returns the videos inside one of a creator's profile playlists, in playlist order, ten per page. Each video carries the full set of engagement counts, the caption, the author, and a playable URL. Get the `playlist_id` from `/v1/tiktok/profile/playlists`. Page with `cursor`: the value the previous response returned must be sent back unchanged, because it is the upstream's own item index and is not always the number of rows you have already received.", "tags": [ "tiktok" ], "operationId": "get_tiktok_playlist_videos", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-socialcrawl-oneOf": [ [ "handle", "user_id" ] ], "parameters": [ { "name": "playlist_id", "in": "query", "required": true, "description": "Playlist id from /v1/tiktok/profile/playlists (`post.id` on that response).", "schema": { "type": "string" }, "example": "7229371484127382314" }, { "name": "handle", "in": "query", "required": false, "description": "TikTok username of the playlist owner, without the @ symbol. (one of: handle, user_id; at least one required)", "schema": { "type": "string" }, "example": "chipotle" }, { "name": "user_id", "in": "query", "required": false, "description": "TikTok numeric user ID of the playlist owner. Use this for faster responses. (one of: handle, user_id; at least one required)", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from the previous response to fetch the next page of videos.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.", "schema": { "type": "string" } }, { "name": "max_pages", "in": "query", "required": false, "description": "1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "max_items", "in": "query", "required": false, "description": "1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: \"max_items\"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`\"time_budget\"`): send the returned cursor with the same params to continue.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "max_credits", "in": "query", "required": false, "description": "1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: \"max_credits\"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/playlist/videos" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical post wrappers ({ post, computed })", "items": { "type": "object", "description": "Canonical post wrapper", "properties": { "post": { "type": "object", "description": "Canonical Post object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "integer", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "integer", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "integer", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "integer", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "integer", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "integer", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "string", "null" ], "description": "Leaf at computed.labels" }, "labels_evidence": { "type": [ "string", "null" ], "description": "Leaf at computed.labels_evidence" } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/playlist/videos", "data": { "items": [ { "post": { "id": "7227314078543367466", "url": "https://www.tiktok.com/@chipotle/video/7227314078543367466", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://v45.tiktokcdn-eu.com/e11d779171c802075c5ddb408310ce92/6ac0aea5/video/tos/alisg/tos-alisg-ve-37c799-sg/ow9fZAysJSgkLDokyT8bDBgRoJaFOUQeRXn1EL/?a=1233&bti=OTg7QGo2NHYpNzo5Zi0wM2AjLzptNDQwOg%3D%3D&&bt=1602&ft=eln4b2WCjBk9w8cLOiXgp0~OJhjwPopiP6.W-ZBMEeF&mime_type=video_mp4&rc=ZzdoPDk1MzlpOmU3ZmUzNEBpM25xcWc6ZjU8azMzZzczNEAwLTJiYjJgNmMxNF41L2MzYSMyZmhjcjRvNDNgLS1kMS9zcw%3D%3D&vvpl=1&l=2026100207273905FA9BE1BFC97FEB1E60&btag=e0008d000", "thumbnail_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/1994ffefaad34a9aaec59900ba67fc66_1682740206~tplv-tiktokx-dmt-logoccm:300:400:tos-useast5-i-0068-tx/cc9119474b12404194d6790ae5d56f13.heic?dr=9231&refresh_token=0bdc7662&x-expires=1791010800&x-signature=F%2F3DQTtabrNPt2y9OrW%2BgM7rljg%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=1d1a97fc&idc=no1a&biz_tag=tt_video&s=TIKTOK_MIX_ITEM_LIST&sc=cover", "duration_seconds": 59.023 }, "author": { "username": "chipotle", "display_name": "user_028b46", "avatar_url": "https://example.com/avatars/user_666dd7.png", "verified": false }, "engagement": { "views": 2460722, "likes": 11429, "comments": 90, "shares": 191, "saves": 273 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2023-04-29T03:50:05.000Z", "ext": { "music_id": "6954420568222107650", "author_id": "user_f64440", "author_followers": 0, "download_count": 23, "published_at_epoch": 1682740205 } }, "computed": { "engagement_rate": 0.004759, "language": null, "content_category": "other", "estimated_reach": 2952866 } }, { "post": { "id": "7226907314966646059", "url": "https://www.tiktok.com/@chipotle/video/7226907314966646059", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://v45.tiktokcdn-eu.com/8bc4f09a0646f5e96774306330d50880/6ac0ae9f/video/tos/alisg/tos-alisg-ve-37c799-sg/o4MUwhCQIDxIyAINLP0J5ZiwZ7rzCAfKpxcBDM/?a=1233&bti=OTg7QGo2NHYpNzo5Zi0wM2AjLzptNDQwOg%3D%3D&&bt=1906&ft=eln4b2WCjBk9w8cLOiXgp0~OJhjwPopiP6.W-ZBMEeF&mime_type=video_mp4&rc=NjM3NmhkNjk4aDNnMztoZUBpM3U3cDU6ZjhsazMzZzczNEBiYl8xLWMtXjExYmMyYDU2YSNubWJscjQwMDJgLS1kMS9zcw%3D%3D&vvpl=1&l=2026100207273905FA9BE1BFC97FEB1E60&btag=e0008d000", "thumbnail_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/5f5e3d947a3442f2969c2dd6f6245b33_1682645491~tplv-tiktokx-dmt-logoccm:300:400:tos-useast5-i-0068-tx/2150d3957a32404ea31705453c83ba5f.heic?dr=9231&refresh_token=a8a7fe04&x-expires=1791010800&x-signature=xpHlFO13pSOLUqN8p1iQb%2BTba34%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=1d1a97fc&idc=no1a&biz_tag=tt_video&s=TIKTOK_MIX_ITEM_LIST&sc=cover", "duration_seconds": 52.637 }, "author": { "username": "chipotle", "display_name": "user_028b46", "avatar_url": "https://example.com/avatars/user_666dd7.png", "verified": false }, "engagement": { "views": 2037831, "likes": 14238, "comments": 77, "shares": 180, "saves": 253 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2023-04-28T01:31:30.000Z", "ext": { "music_id": "7029076048919447553", "author_id": "user_f64440", "author_followers": 0, "download_count": 18, "published_at_epoch": 1682645490 } }, "computed": { "engagement_rate": 0.007113, "language": "en", "content_category": "other", "estimated_reach": 2445397 } } ], "total": null, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": null, "has_more": false, "page_size": 3 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T07:27:40.553Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/user/liked": { "get": { "summary": "List the videos a TikTok account has liked", "description": "Returns the videos a given TikTok account has liked, newest first, thirty per page. This is the account's own likes feed and it reads in one direction only: it answers what this user liked, not who liked a given video. There is no endpoint for the other direction, on this API or any other, because TikTok keeps the identity of the people who like a post private. Each row is another creator's video and carries that creator's author block, engagement counts and caption. Most accounts keep their likes list private: when they do, the response is `404 RESOURCE_NOT_FOUND` and the request is refunded. Check `author.ext` on `/v1/tiktok/profile` first if you want to know before you call. Page with `cursor`, sending back the value from the previous response unchanged.", "tags": [ "tiktok" ], "operationId": "get_tiktok_user_liked", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-socialcrawl-oneOf": [ [ "handle", "user_id" ] ], "parameters": [ { "name": "handle", "in": "query", "required": false, "description": "TikTok username without the @ symbol. (one of: handle, user_id; at least one required)", "schema": { "type": "string" }, "example": "chipotle" }, { "name": "user_id", "in": "query", "required": false, "description": "TikTok numeric user ID. Use this for faster responses. (one of: handle, user_id; at least one required)", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from the previous response to fetch the next page of liked videos.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.", "schema": { "type": "string" } }, { "name": "max_pages", "in": "query", "required": false, "description": "1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "max_items", "in": "query", "required": false, "description": "1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: \"max_items\"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`\"time_budget\"`): send the returned cursor with the same params to continue.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "max_credits", "in": "query", "required": false, "description": "1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: \"max_credits\"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/user/liked" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical post wrappers ({ post, computed })", "items": { "type": "object", "description": "Canonical post wrapper", "properties": { "post": { "type": "object", "description": "Canonical Post object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "integer", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "integer", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "integer", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "integer", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "integer", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "integer", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "string", "null" ], "description": "Leaf at computed.labels" }, "labels_evidence": { "type": [ "string", "null" ], "description": "Leaf at computed.labels_evidence" } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/user/liked", "data": { "items": [ { "post": { "id": "7691481939810864398", "url": "https://www.tiktok.com/@user_8b3bdf/video/7691481939810864398", "content": { "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "media_urls": "https://v16m.tiktokcdn-eu.com/bdfcb46e2c447479f334d569670e5590/6ac1225e/video/tos/alisg/tos-alisg-ve-37c799-sg/oYoDbIqI7m0D8BMRgaSKafETFEARtgv1fumLWQ/?a=1233&bti=N3YpOzs8Zik3OjlmOm0wMjI6ZDQ0MDo%3D&&bt=921&ft=XsFb8q4fmbdPD12r48MI3wUONMtwMeF~O5&mime_type=video_mp4&rc=ODpmZzU5ODY2NjY0aWQ2ZEBpanRzdnQ5cjl0ZDMzZzczNEBeM2IvXjUwXzExMzUxYDU0YSNfM2xmMmRrMXJhLS1kMS9zcw%3D%3D&vvpl=1&l=20261002154042EA6738841032F42A11FF&btag=e00088000", "thumbnail_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooEMraQgSeAFuEaRVjR01vfmgIDODBzQmHEqL7~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=1d977d34&x-expires=1791039600&x-signature=dQ5M3vrc%2B7tIRA5BWx4VN8Ur3r4%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=fb0ad5ba&idc=no1a&biz_tag=tt_video&s=FAVORITE&sc=cover", "duration_seconds": 99.7 }, "author": { "username": "user_8b3bdf", "display_name": "user_8b3bdf", "avatar_url": "https://example.com/avatars/user_bd8f04.png", "verified": false }, "engagement": { "views": 254418, "likes": 29840, "comments": 105, "shares": 1775, "saves": 4543 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2026-09-30T23:58:25.000Z", "ext": { "music_id": "7691481916788329229", "author_id": "user_742c9c", "download_count": 87, "published_at_epoch": 1790812705 } }, "computed": { "engagement_rate": 0.124677, "language": "ja", "content_category": "other", "estimated_reach": 305302 } }, { "post": { "id": "7690641494612413727", "url": "https://www.tiktok.com/@user_c4fdd8/video/7690641494612413727", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://v16m.tiktokcdn-eu.com/e21324a983b737a110d50c9b5845042f/6ac12237/video/tos/alisg/tos-alisg-ve-37c799-sg/owdAsCIUeYGFjUAenupQLG1IelqgdVIIS7QVLK/?a=1233&bti=N3YpOzs8Zik3OjlmOm0wMjI6ZDQ0MDo%3D&&bt=383&ft=XsFb8q4fmbdPD12r48MI3wUONMtwMeF~O5&mime_type=video_mp4&rc=Z2Q3NztpOjk1ZDU7aTQ3O0BpM2l1cnM5cnRkZDMzaTczNEAzNjJhNWJiX18xMy9gMzNeYSNfNWthMmRrNnFhLS1kMTJzcw%3D%3D&vvpl=1&l=20261002154042EA6738841032F42A11FF&btag=e00088000", "thumbnail_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-useast8-p-0068-tx2/owIj7XQ6leqLoKGQCAesLuAqFnQec1vVIUdVpI~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=55a95deb&x-expires=1791039600&x-signature=CiiHVW6SC3lYtmazm9gFews4S4k%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=fb0ad5ba&idc=no1a&sc=cover&biz_tag=tt_video&s=FAVORITE", "duration_seconds": 60.367 }, "author": { "username": "user_c4fdd8", "display_name": "user_c4fdd8", "avatar_url": "https://example.com/avatars/user_4ad5e2.png", "verified": false }, "engagement": { "views": 1956405, "likes": 375263, "comments": 1480, "shares": 88640, "saves": 22149 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2026-09-28T17:37:12.000Z", "ext": { "music_id": "7690641560106535711", "author_id": "user_8c06e3", "download_count": 761, "published_at_epoch": 1790617032 } }, "computed": { "engagement_rate": 0.237877, "language": null, "content_category": "other", "estimated_reach": 2347686 } } ], "next_cursor": "1790279192000000", "total": null, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiMTc5MDI3OTE5MjAwMDAwMCIsImUiOiJ0aWt0b2svdXNlci9saWtlZCIsInAiOiJjdXJzb3IifQ", "has_more": true, "page_size": 30 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T15:40:42.246Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/location/posts": { "get": { "summary": "List TikTok videos tagged at a place", "description": "Returns public videos tagged at a TikTok place, twenty per page, with full engagement counts and author details on every row. `location_id` is TikTok's own place id, the number that appears in a place page URL. A place id TikTok does not recognise returns `404 RESOURCE_NOT_FOUND` and is refunded, which is distinct from a real place that simply has no recent posts: that returns an empty list.", "tags": [ "tiktok" ], "operationId": "get_tiktok_location_posts", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "location_id", "in": "query", "required": true, "description": "TikTok place id, as it appears in the place page URL.", "schema": { "type": "string" }, "example": "22535865202815278" }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from the previous response to fetch the next page of videos.", "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "description": "Two-letter country code for the proxy location. Defaults to US.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.", "schema": { "type": "string" } }, { "name": "max_pages", "in": "query", "required": false, "description": "1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "max_items", "in": "query", "required": false, "description": "1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: \"max_items\"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`\"time_budget\"`): send the returned cursor with the same params to continue.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "max_credits", "in": "query", "required": false, "description": "1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: \"max_credits\"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/location/posts" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical post wrappers ({ post, computed })", "items": { "type": "object", "description": "Canonical post wrapper", "properties": { "post": { "type": "object", "description": "Canonical Post object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "integer", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "integer", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "integer", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "integer", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "integer", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "integer", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "string", "null" ], "description": "Leaf at computed.labels" }, "labels_evidence": { "type": [ "string", "null" ], "description": "Leaf at computed.labels_evidence" } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/location/posts", "data": { "items": [ { "post": { "id": "7623592701052734727", "url": "https://www.tiktok.com/@user_f2dbde/video/7623592701052734727", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://v16m.tiktokcdn-us.com/c0191ac6067e56f41cf2cd3b9bd22521/6abfb188/video/tos/alisg/tos-alisg-ve-0068c800-sg/osGYboe5RCwmogIpoej4IeTDKHBUOA05AXAyLT/?a=1233&bti=OzR2KTQ7PEBqOjo2QC86bTQ1MC5gIzE0M2A%3D&&bt=1834&ft=gKfIn8s6ogVP12NvZJ6qzIxR4FBO63_45SY&mime_type=video_mp4&rc=ZmUzOzQ6ZDQ5O2dkNzQzOUBpamc7eW45cnk6OjMzODczNEA1MjYzYGBhNWMxMi4uMmFhYSMvbGduMmQ0LjNhLS1kMTFzcw%3D%3D&vvpl=1&l=20261002072744B0520517838B1F230E23&btag=e00088000", "thumbnail_url": "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/osIRDUpAHlDrk8FMDBIMNzFvN2FBagfpEcEneT~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=8596&refresh_token=465538b6&x-expires=1791010800&x-signature=y4qzJbDwcsH01laibCalsTOpdZU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=c0f880ed&idc=useast5&biz_tag=tt_video&s=POI_VIDEO&sc=cover", "duration_seconds": 56.3 }, "author": { "username": "user_f2dbde", "display_name": "user_63292a", "avatar_url": "https://example.com/avatars/user_c55a8b.png", "verified": false }, "engagement": { "views": 1459539, "likes": 108612, "comments": 883, "shares": 7082, "saves": 15178 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2026-04-01T01:13:22.000Z", "ext": { "music_id": "7623592755168185089", "author_id": "user_387df1", "download_count": 2757, "published_at_epoch": 1775006002 } }, "computed": { "engagement_rate": 0.079872, "language": "ko", "content_category": "other", "estimated_reach": 1751447 } }, { "post": { "id": "7633767260557069589", "url": "https://www.tiktok.com/@user_d73393/video/7633767260557069589", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://v16m.tiktokcdn-us.com/5b682b3bf90b42f5f28a22167635dc9d/6abfb176/video/tos/alisg/tos-alisg-ve-0068c800-sg/okEtxRREQBAfjIHhgpbgAwGQcBFbqL8DJfFZ6y/?a=1233&bti=OzR2KTQ7PEBqOjo2QC86bTQ1MC5gIzE0M2A%3D&&bt=1844&ft=gKfIn8s6ogVP12NvZJ6qzIxR4FBO63_45SY&mime_type=video_mp4&rc=ZDVnOTxoaGU6aTQ2ZWc6PEBpM281anM5cnA8OjMzODczNEAuNmMuYjFiNjMxMV5eMWEwYSNgZDAuMmRjYWxhLS1kMWBzcw%3D%3D&vvpl=1&l=20261002072744B0520517838B1F230E23&btag=e00088000", "thumbnail_url": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/osQhQKBXRLx8AaDpGFHTfqeAwbyEZE4gcQJdBr~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=8596&refresh_token=b4365102&x-expires=1791010800&x-signature=xvlYpKduytkrmA07RiJQF9FvgLM%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=c0f880ed&idc=useast5&biz_tag=tt_video&s=POI_VIDEO&sc=cover", "duration_seconds": 38.683 }, "author": { "username": "user_d73393", "display_name": "user_e3e3b6", "avatar_url": "https://example.com/avatars/user_57fad9.png", "verified": false }, "engagement": { "views": 1424456, "likes": 148268, "comments": 1192, "shares": 13390, "saves": 26246 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2026-04-28T11:15:51.000Z", "ext": { "music_id": "7633767311636515605", "author_id": "user_fff7b4", "download_count": 2993, "published_at_epoch": 1777374951 } }, "computed": { "engagement_rate": 0.114324, "language": "ko", "content_category": "other", "estimated_reach": 1709347 } } ], "next_cursor": "20", "total": null, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiMjAiLCJlIjoidGlrdG9rL2xvY2F0aW9uL3Bvc3RzIiwicCI6ImN1cnNvciJ9", "has_more": true, "page_size": 20 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T07:27:46.099Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/effects": { "get": { "summary": "Get TikTok effects by id", "description": "Looks up TikTok effects (the camera filters creators apply to a video) by id, up to 50 in one request for a single credit. Each row carries the effect name, its designer, the total views of videos made with it under `post.engagement.views`, and the number of such videos under `post.ext.video_count`. Match results by the returned `post.id`, never by position: repeated ids are collapsed into one row and ids TikTok does not recognise are omitted, so the response can be shorter than the list you sent. A request in which no id is recognised returns `404 RESOURCE_NOT_FOUND` and is refunded.", "tags": [ "tiktok" ], "operationId": "get_tiktok_effects", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "ids", "in": "query", "required": true, "description": "Comma-separated TikTok effect ids, up to 50 per request.", "schema": { "type": "string" }, "example": "1108584,1109028" }, { "name": "since", "in": "query", "required": false, "description": "Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.", "schema": { "type": "string" } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/effects" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical post wrappers ({ post, computed })", "items": { "type": "object", "description": "Canonical post wrapper", "properties": { "post": { "type": "object", "description": "Canonical Post object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "integer", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "integer", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "integer", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "integer", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "integer", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "integer", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "string", "null" ], "description": "Leaf at computed.labels" }, "labels_evidence": { "type": [ "string", "null" ], "description": "Leaf at computed.labels_evidence" } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/effects", "data": { "items": [ { "post": { "id": "1108584", "url": "https://www.tiktok.com/sticker/effect-1108584", "content": { "text": "Sample comment text (redacted).", "media_urls": null, "thumbnail_url": "https://lf16-effectcdn-sg.tiktokcdn.com/obj/ies.fe.effect.alisg/acf2eb0c12e95ebefda328663c385a9d", "duration_seconds": null }, "author": { "username": null, "display_name": "user_1bb6fc", "avatar_url": "https://example.com/avatars/user_d33c46.png", "verified": false }, "engagement": { "views": 11856482751, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2021-08-18T08:47:07.000Z", "ext": { "published_at_epoch": 1629276427000, "description": "", "video_count": 15865470 } }, "computed": { "engagement_rate": null, "language": null, "content_category": "other", "estimated_reach": 14227779301 } }, { "post": { "id": "1109028", "url": "https://www.tiktok.com/sticker/peppery-filter-1109028", "content": { "text": "Sample comment text (redacted).", "media_urls": null, "thumbnail_url": "https://lf16-effectcdn-sg.tiktokcdn.com/obj/ies.fe.effect.alisg/45cabb4840604cc24296d058810f28e8", "duration_seconds": null }, "author": { "username": null, "display_name": "user_1bb6fc", "avatar_url": "https://example.com/avatars/user_d33c46.png", "verified": false }, "engagement": { "views": 19541397609, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2021-08-18T08:57:21.000Z", "ext": { "published_at_epoch": 1629277041000, "description": "", "video_count": 15865470 } }, "computed": { "engagement_rate": null, "language": null, "content_category": "other", "estimated_reach": 23449677131 } } ], "total": null, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": null, "has_more": false, "page_size": 2 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T13:11:40.556Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/effect/videos": { "get": { "summary": "List TikTok videos made with an effect", "description": "Returns public videos created with a TikTok effect, with full engagement counts and author details on every row. TikTok chooses its own page size here and it does not track the number you ask for, so send the `cursor` from the previous response back unchanged rather than adding up the rows you have received. An effect id TikTok does not recognise returns `404 RESOURCE_NOT_FOUND` and is refunded.", "tags": [ "tiktok" ], "operationId": "get_tiktok_effect_videos", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "effect_id", "in": "query", "required": true, "description": "TikTok effect id, as returned by /v1/tiktok/effects.", "schema": { "type": "string" }, "example": "1108584" }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from the previous response to fetch the next page of videos.", "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "description": "Two-letter country code for the proxy location. Defaults to US.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.", "schema": { "type": "string" } }, { "name": "max_pages", "in": "query", "required": false, "description": "1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "max_items", "in": "query", "required": false, "description": "1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: \"max_items\"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`\"time_budget\"`): send the returned cursor with the same params to continue.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "max_credits", "in": "query", "required": false, "description": "1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: \"max_credits\"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/effect/videos" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical post wrappers ({ post, computed })", "items": { "type": "object", "description": "Canonical post wrapper", "properties": { "post": { "type": "object", "description": "Canonical Post object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "integer", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "integer", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "integer", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "integer", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "integer", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "integer", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "string", "null" ], "description": "Leaf at computed.labels" }, "labels_evidence": { "type": [ "string", "null" ], "description": "Leaf at computed.labels_evidence" } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/effect/videos", "data": { "items": [ { "post": { "id": "7006406506199518470", "url": "https://www.tiktok.com/@user_6d31d3/video/7006406506199518470", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://v16m.tiktokcdn-us.com/f4a3706518ef6c7531779130016b8812/6abfb15a/video/tos/useast2a/tos-useast2a-ve-0068c004/c33c4c197ad74a6aa08171b641d465e1/?a=1233&bti=O0BzNjQ6QGo6OjZALnAjLzYzYCMxNDNg&&bt=852&ft=gKfIn8buoTfR12NvKJ6qzIxR._PhZQ_45SY&mime_type=video_mp4&rc=ZGY4OWQzZzs5ZjpkNWg1Z0BpM25rMzc6Zjh2NzMzNzczM0AwYmMwNi5iX18xYi4yNTQ1YSNqay4vcjRnMHFgLS1kMTZzcw%3D%3D&vvpl=1&l=2026100207274703128E2FF45B91CB8A15&btag=e000b0000", "thumbnail_url": "https://p19-common-sign.tiktokcdn-us.com/tos-maliva-p-0068/b38618fbf7914c1d91d69e16cb3eaef9~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=8596&refresh_token=c53ee783&x-expires=1791010800&x-signature=FmITDcPfqcWGCtYOcQaDeiCz34g%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=8b85b4fa&idc=useast5&biz_tag=tt_video&s=STICKER_AWEME&sc=cover", "duration_seconds": 7.173 }, "author": { "username": "user_6d31d3", "display_name": "user_feb032", "avatar_url": "https://example.com/avatars/user_759f8e.png", "verified": true }, "engagement": { "views": 32404382, "likes": 5156712, "comments": 6726, "shares": 43536, "saves": 171459 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2021-09-10T20:35:38.000Z", "ext": { "music_id": "6935116694239169286", "author_id": "user_aa297c", "download_count": 88632, "published_at_epoch": 1631306138 } }, "computed": { "engagement_rate": 0.160687, "language": null, "content_category": "other", "estimated_reach": 38885258 } }, { "post": { "id": "7006300639940594946", "url": "https://www.tiktok.com/@user_80a410/video/7006300639940594946", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://v16m.tiktokcdn-us.com/9746ecebc00b6b4dc54e9fd0ffc693c7/6abfb15a/video/tos/alisg/tos-alisg-pve-0037c001/9e6c549f01b4497baffe01cbf7c0a0ed/?a=1233&bti=O0BzNjQ6QGo6OjZALnAjLzYzYCMxNDNg&&bt=1872&ft=gKfIn8buoTfR12NvKJ6qzIxR._PhZQ_45SY&mime_type=video_mp4&rc=aDQ4PDs4ODQzZzY7NDdoZkBpMzxqZjw6Zm1wNzMzODczNEAxYzRgMTJeXzUxNTUuYWAyYSNzcGxecjRfL3FgLS1kMS1zcw%3D%3D&vvpl=1&l=2026100207274703128E2FF45B91CB8A15&btag=e000f0000", "thumbnail_url": "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/ea1557f8048d42e28d3fdc851fb1c1fb_1631281491~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=8596&refresh_token=7bee087d&x-expires=1791010800&x-signature=dxf2nq%2BWnyqEWtXVEXMrHsRcXfI%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=8b85b4fa&idc=useast5&biz_tag=tt_video&s=STICKER_AWEME&sc=cover", "duration_seconds": 7.382 }, "author": { "username": "user_80a410", "display_name": "user_80a410", "avatar_url": "https://example.com/avatars/user_30064c.png", "verified": false }, "engagement": { "views": 24075036, "likes": 4387145, "comments": 21465, "shares": 17575, "saves": 151074 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2021-09-10T13:44:48.000Z", "ext": { "music_id": "6996850175440423685", "author_id": "user_dce442", "download_count": 47591, "published_at_epoch": 1631281488 } }, "computed": { "engagement_rate": 0.18385, "language": null, "content_category": "other", "estimated_reach": 28890043 } } ], "next_cursor": "40", "total": null, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiNDAiLCJlIjoidGlrdG9rL2VmZmVjdC92aWRlb3MiLCJwIjoiY3Vyc29yIn0", "has_more": true, "page_size": 32 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T07:27:48.956Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/search/music": { "get": { "summary": "Search TikTok sounds", "description": "Searches TikTok's sound catalogue by keyword and returns up to thirty matching sounds per page, each with its title, artist, duration, cover art, a preview audio URL, and the number of videos using it under `post.ext.video_count`. Where TikTok knows the track on the major music stores, `post.ext.dsp_ids` carries its Apple Music, Spotify and Amazon ids, which is what makes a sound joinable to catalogue data outside TikTok. `post.ext.matched_song_id` is the catalogue song the sound plays, the same id video rows carry: one song can sit behind several official sounds, so searching a video's `matched_song_title` and `matched_song_artist` and keeping the sounds whose `matched_song_id` equals the video's finds every official sound of that song, each with its own `video_count`. Pass `post.ext.music_id` to `/v1/tiktok/song/videos` to see the videos using a sound.", "tags": [ "tiktok" ], "operationId": "get_tiktok_search_music", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search keyword, matched against sound titles and creators.", "schema": { "type": "string" }, "example": "espresso" }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from the previous response to fetch the next page of sounds.", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Result ordering: relevance (default), most-used, most-recent, shortest or longest.", "schema": { "type": "string", "enum": [ "relevance", "most-used", "most-recent", "shortest", "longest" ] } }, { "name": "filter_by", "in": "query", "required": false, "description": "Which field the keyword is matched against: all (default), title or creators.", "schema": { "type": "string", "enum": [ "all", "title", "creators" ] } }, { "name": "region", "in": "query", "required": false, "description": "Two-letter country code for the proxy location. Defaults to US.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.", "schema": { "type": "string" } }, { "name": "max_pages", "in": "query", "required": false, "description": "1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "max_items", "in": "query", "required": false, "description": "1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: \"max_items\"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`\"time_budget\"`): send the returned cursor with the same params to continue.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "max_credits", "in": "query", "required": false, "description": "1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: \"max_credits\"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/search/music" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical post wrappers ({ post, computed })", "items": { "type": "object", "description": "Canonical post wrapper", "properties": { "post": { "type": "object", "description": "Canonical Post object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "integer", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "integer", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "integer", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "integer", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "integer", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "integer", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "string", "null" ], "description": "Leaf at computed.labels" }, "labels_evidence": { "type": [ "string", "null" ], "description": "Leaf at computed.labels_evidence" } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/search/music", "data": { "items": [ { "post": { "id": "7364498342501435408", "url": "https://www.tiktok.com/music/espresso-7364498342501435408", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://sf16.tiktokcdn-us.com/obj/tos-alisg-ve-2774/oMpGBf2aWiooMLdSvOzwiAB0ImsjBhk3IAl1FN", "thumbnail_url": "https://p16-common.tiktokcdn-us.com/tos-alisg-v-2774/ogJppeAaeFIhUSBfAGzM6KCgBIDgLaAUsQAI0D~tplv-tiktokx-cropcenter:720:720.jpeg?dr=9584&t=4d5b0474&ps=933b5bde&shp=08d74b56&shcp=544a444f&idc=useast8", "duration_seconds": 60 }, "author": { "username": null, "display_name": "user_7c4ebf", "avatar_url": null, "verified": false }, "engagement": { "views": null, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2024-05-02T20:23:58.000Z", "ext": { "music_id": "7364498342501435408", "published_at_epoch": 1714681438, "video_count": 525107, "dsp_ids": { "apple_music": "1744253558", "amazon": "B0D16T2QXP", "spotify": "0zoNoIuzPDR1KNUcsjF5TW" } } }, "computed": { "engagement_rate": null, "language": null, "content_category": null, "estimated_reach": null } }, { "post": { "id": "7369680652205459472", "url": "https://www.tiktok.com/music/espresso-on-vacation-version-7369680652205459472", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://sf19.tiktokcdn-us.com/obj/tos-alisg-ve-2774/o4SzIOB1IAAi1J3tfWBwMwcij4HDxhGjYyzsoE", "thumbnail_url": "https://p19-common.tiktokcdn-us.com/tos-alisg-v-2774/o8IvETBmBgAE9BZsAiCXfAZCHf7BRiwFxQ1Ert~tplv-tiktokx-cropcenter:720:720.jpeg?dr=9584&t=4d5b0474&ps=933b5bde&shp=08d74b56&shcp=544a444f&idc=useast8", "duration_seconds": 60 }, "author": { "username": null, "display_name": "user_7c4ebf", "avatar_url": null, "verified": false }, "engagement": { "views": null, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2024-05-16T19:55:10.000Z", "ext": { "music_id": "7369680652205459472", "published_at_epoch": 1715889310, "video_count": 205849, "dsp_ids": { "apple_music": "1746801012", "amazon": "B0D4BZTTZ6", "spotify": "5WszdMXh1g7EFgJcfJd3cQ" } } }, "computed": { "engagement_rate": null, "language": null, "content_category": "other", "estimated_reach": null } } ], "next_cursor": "30", "total": 299, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiMzAiLCJlIjoidGlrdG9rL3NlYXJjaC9tdXNpYyIsInAiOiJjdXJzb3IifQ", "has_more": true, "page_size": 27 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T07:27:51.242Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/hashtag": { "get": { "summary": "Get TikTok hashtag details", "description": "Returns TikTok's own record for a hashtag: its display name, its description where the platform has written one, and the two numbers that size it. `post.engagement.views` is the total views of videos under the tag and it is live, moving between calls minutes apart. `post.ext.video_count` is how many videos carry the tag. Pass either the tag name or, if you already have it, TikTok's numeric hashtag id. Use `/v1/tiktok/search/hashtag` to read the videos themselves.", "tags": [ "tiktok" ], "operationId": "get_tiktok_hashtag", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-socialcrawl-oneOf": [ [ "hashtag", "hashtag_id" ] ], "parameters": [ { "name": "hashtag", "in": "query", "required": false, "description": "Hashtag name, with or without the leading # symbol. (one of: hashtag, hashtag_id; at least one required)", "schema": { "type": "string" }, "example": "kpop" }, { "name": "hashtag_id", "in": "query", "required": false, "description": "TikTok numeric hashtag id. Skips the name lookup when you already have it. (one of: hashtag, hashtag_id; at least one required)", "schema": { "type": "string" } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/hashtag" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } } }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/hashtag", "data": { "post": { "id": "6985", "url": "https://www.tiktok.com/tag/kpop", "content": { "text": "kpop", "media_urls": null, "thumbnail_url": "https://p16-common-sign.tiktokcdn-eu.com/musically-maliva-obj/1bc2a8c67b228193034d8d1634d85583.jpeg~tplv-tiktokx-origin.image?dr=10386&refresh_token=3125a45a&x-expires=1790982000&x-signature=THz250Pmd5OgWr3yQYHpqQ%2FJ8KY%3D&t=4d5b0474&ps=13740610&shp=3d78c6bd&shcp=9b759fb9&idc=no1a&plt=gomtdiscovery_challenge_banner", "duration_seconds": null }, "author": { "username": null, "display_name": null, "avatar_url": null, "verified": false }, "engagement": { "views": 1063158803158, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": null, "ext": { "description": "No matter who you stan, we're here for all things #KPop.", "video_count": 75679537 } }, "computed": { "engagement_rate": null, "language": null, "content_category": null, "estimated_reach": 1275790563790 } }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T13:11:12.430Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/ads/top": { "get": { "summary": "Read TikTok's Creative Center Top Ads board: the best-performing ads in a market, ranked by CTR, impressions or engagement. Metered: 1 credit per ad returned, minimum 10", "description": "Returns TikTok's own leaderboard of top-performing ads for a market and time window, with the performance signals TikTok publishes and nothing else does: `ext.ad.ctr` is the click-through rate, `ext.ad.rank` is the ad's position on the board, `ext.ad.cost_score` and `ext.ad.like_tier` are TikTok's own banded cost and engagement tiers, and `engagement.likes` is the real like count. Each row carries the ad's video at `content.media_urls` (720p, with 540p and 360p renditions on `ext.ad`), the cover image, the duration, the advertiser at `author.username`, and the campaign objective and industry at `ext.ad.objective` / `ext.ad.industry`. **This is a different surface from `/v1/tiktok/adlibrary/search`.** That endpoint reads the EU Commercial Content Library, which carries who an ad was targeted at across 33 EU/EEA countries but publishes no performance data; this one reads the global Creative Center board across 24 markets including the US, Korea, Japan and Brazil, and publishes performance but no targeting. Use this one to find creative that worked, and that one to find who an advertiser bought. **There is no publish date**: TikTok does not attach one to the board, so `published_at` is null on every row rather than filled with the time you called. `brandName` is absent on roughly half of live rows because TikTok attributes some top ads to no brand, so `author.username` is null there too. **2-second and 6-second view rates:** `order_by=play_2s_rate` and `order_by=play_6s_rate` rank the board by TikTok's own view-rate figures, which TikTok uses for the ranking and does not publish as numbers. What TikTok publishes for each ad is its second-by-second audience retention curve: send `include=retention` and every row carries `ext.ad.retention` (one `{second, value}` point per second, the share of viewers still watching, 1 at second 0), with `ext.ad.retention_2s` and `ext.ad.retention_6s` the points at second 2 and second 6 (null when the ad is shorter than that). These are TikTok's curve values, not the figure it sorts by, so the board's order and the 6-second points do not always agree. `include=retention` reads up to 20 ads per call, usually takes 20 to 35 seconds, and cannot be combined with `keyword` or `industry`. **Pricing is metered at 1 credit per ad RETURNED, with a minimum of 10** — the board is served in blocks of ten, so a smaller `limit` still costs ten.", "tags": [ "tiktok" ], "operationId": "get_tiktok_ads_top", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 10, "x-credit-cost-min": 10, "x-credit-cost-max": 100, "x-credit-cost-formula": "1 credit per ad returned, minimum 10 credits. A limit of 20 holds 20 credits and settles down to the number of ads that actually came back; a filter combination with no board costs nothing. With include=retention, 2 credits per ad that carries a retention curve (minimum 20), and 1 per ad TikTok serves no curve for.", "parameters": [ { "name": "country", "in": "query", "required": false, "description": "Creative Center market to read the board for. Defaults to US. This is the market the ads ran in, not the language they are in.", "schema": { "type": "string", "enum": [ "US", "CA", "MX", "BR", "GB", "DE", "FR", "IT", "ES", "NL", "PL", "SE", "TR", "SA", "AE", "AU", "JP", "KR", "ID", "TH", "VN", "MY", "PH", "SG" ] }, "example": "US" }, { "name": "period", "in": "query", "required": false, "description": "Lookback window in days: 7, 30 or 180. Defaults to 30. A longer window is a different board, not more rows.", "schema": { "type": "string", "enum": [ "7", "30", "180" ] }, "example": "30" }, { "name": "order_by", "in": "query", "required": false, "description": "How TikTok ranks the board: for_you (TikTok's own blend, the default), ctr, impression, like, cvr, play_2s_rate or play_6s_rate.", "schema": { "type": "string", "enum": [ "for_you", "impression", "ctr", "play_2s_rate", "play_6s_rate", "cvr", "like" ] }, "example": "ctr" }, { "name": "ad_format", "in": "query", "required": false, "description": "Restrict to Spark ads (ads boosted from an organic post) or Non-Spark ads. Defaults to all.", "schema": { "type": "string", "enum": [ "All ad types", "Spark ads", "Non-Spark ads" ] } }, { "name": "ad_language", "in": "query", "required": false, "description": "Filter by the language of the ad copy.", "schema": { "type": "string", "enum": [ "en", "ja", "zh", "vi", "th", "pt", "id" ] } }, { "name": "like_tier", "in": "query", "required": false, "description": "TikTok's engagement percentile band, 1 (top) to 5. Use it to read further down the ranking without raising limit.", "schema": { "type": "string", "enum": [ "1", "2", "3", "4", "5" ] } }, { "name": "industry", "in": "query", "required": false, "description": "Creative Center sub-category label, for example 'Skincare' or 'Cosmetics'. Use a sub-category, not a top-level group: the board returns nothing for the broad groups such as 'Financial Services' or 'Education'. Omit for all industries.", "schema": { "type": "string" } }, { "name": "keyword", "in": "query", "required": false, "description": "Search the board by brand or product keyword.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many ads to return, 1-100, default 20. The board is served in blocks of ten, so any limit below 10 still costs 10 credits. With include=retention, 1-20.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "include", "in": "query", "required": false, "description": "Send `retention` to add each ad's second-by-second audience retention curve (`ext.ad.retention`) and its points at second 2 and second 6 (`ext.ad.retention_2s`, `ext.ad.retention_6s`). 2 credits per ad that carries a curve, minimum 20; up to 20 ads per call; usually 20 to 35 seconds; not combinable with keyword or industry.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.", "schema": { "type": "string" } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/ads/top" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical post wrappers ({ post, computed })", "items": { "type": "object", "description": "Canonical post wrapper", "properties": { "post": { "type": "object", "description": "Canonical Post object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "integer", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "integer", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "integer", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "integer", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "integer", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "integer", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "integer", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked. Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "integer", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "upvote_ratio": { "type": [ "integer", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "integer", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "integer", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "integer", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "integer", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "type": "string", "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "type": "string", "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/search/reels` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "string", "null" ], "description": "Leaf at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "string", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "string", "null" ], "description": "Leaf at post.ext.retweeted_post" }, "quote_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "type": "string", "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "string", "null" ], "description": "Leaf at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "string", "description": "Leaf at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "string", "null" ], "description": "Leaf at post.ext.localizations" }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "integer", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "string", "null" ], "description": "Leaf at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "integer", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "string", "null" ], "description": "Leaf at post.ext.dsp_ids" }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "string", "description": "Leaf at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "string", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "string", "null" ], "description": "Leaf at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "integer", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "integer", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "string", "null" ], "description": "Leaf at post.ext.event" }, "trend": { "type": [ "string", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "integer", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "integer", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "integer", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "integer", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "integer", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "integer", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "string", "null" ], "description": "Leaf at computed.labels" }, "labels_evidence": { "type": [ "string", "null" ], "description": "Leaf at computed.labels_evidence" } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/profile/videos", "data": { "items": [ { "post": { "id": "7658005300657638669", "url": "https://www.tiktok.com/@user_ae6bf3/video/7658005300657638669", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000", "thumbnail_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover", "duration_seconds": 16.903 }, "author": { "username": "user_ae6bf3", "display_name": "user_de35a8", "avatar_url": "https://example.com/avatars/user_3c9283.png", "verified": true }, "engagement": { "views": 3417578, "likes": 501973, "comments": 2618, "shares": 6304, "saves": 22989 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2026-07-02T18:51:58.000Z", "ext": { "music_id": "7656080164593437471", "published_at_epoch": 1783018318 } }, "computed": { "engagement_rate": 0.14949, "language": null, "content_category": "other", "estimated_reach": 4101094 } }, { "post": { "id": "7657606229484670221", "url": "https://www.tiktok.com/@user_ae6bf3/video/7657606229484670221", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000", "thumbnail_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover", "duration_seconds": 10.123 }, "author": { "username": "user_ae6bf3", "display_name": "user_de35a8", "avatar_url": "https://example.com/avatars/user_3c9283.png", "verified": true }, "engagement": { "views": 7205601, "likes": 739100, "comments": 1943, "shares": 6268, "saves": 28516 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2026-07-01T17:03:22.000Z", "ext": { "music_id": "7656080164593437471", "published_at_epoch": 1782925402 } }, "computed": { "engagement_rate": 0.103713, "language": null, "content_category": "other", "estimated_reach": 8646721 } }, { "post": { "id": "7657287641641143565", "url": "https://www.tiktok.com/@user_ae6bf3/video/7657287641641143565", "content": { "text": null, "media_urls": "https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000", "thumbnail_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover", "duration_seconds": 6.467 }, "author": { "username": "user_ae6bf3", "display_name": "user_de35a8", "avatar_url": "https://example.com/avatars/user_3c9283.png", "verified": true }, "engagement": { "views": 5941789, "likes": 941067, "comments": 3165, "shares": 17173, "saves": 18760 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2026-06-30T20:27:04.000Z", "ext": { "music_id": "7530783142774065975", "published_at_epoch": 1782851224 } }, "computed": { "engagement_rate": 0.161804, "language": null, "content_category": null, "estimated_reach": 7130147 } } ], "next_cursor": "1782516110000", "total": 10, "dropped": 0 }, "credits_used": 1, "credits_remaining": 9999, "request_id": "req-8Kq2ZmR4vT9xLb3P", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0", "has_more": true, "page_size": 10 }, "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/profile/full": { "get": { "summary": "TikTok profile, recent posts, and computed analytics in one call.", "description": "Fans out to the TikTok profile and recent-posts endpoints in parallel and returns the unified author, the recent-post list, and computed metrics: avg_engagement_rate, avg_engagement_rate_by_followers, posting cadence (with the window it was measured over), the top post, and the format mix. avg_engagement_rate is view-based: the mean of each post's (likes + comments + shares) / views, so only posts that carry a view count contribute, and it is null when none does. avg_engagement_rate_by_followers is the mean of likes + comments per post divided by the account's follower count, over every post that carries both, so it covers posts with no view count. One call reads one page of recent posts, which on TikTok is 10 videos, and computes the metrics over that page: `posts` can shorten the window but not lengthen it past one page, and `_warnings` says so when fewer posts came back than `posts` asked for. Pass `posts_cursor` back as `cursor` to read the next page, 5 credits a call. The profile leg is the only critical leg: if posts can't be fetched the call still returns the profile with post-dependent metrics null, and every leg's status is surfaced in legs[]. Flat 5 credits.", "tags": [ "tiktok" ], "operationId": "get_tiktok_profile_full", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 5, "x-socialcrawl-oneOf": [ [ "handle", "user_id" ] ], "parameters": [ { "name": "handle", "in": "query", "required": false, "description": "TikTok username or handle, with or without a leading @. One of the identity params is required. (one of: handle, user_id; at least one required)", "schema": { "type": "string" }, "example": "mrbeast" }, { "name": "user_id", "in": "query", "required": false, "description": "Numeric TikTok user id. Use it instead of the handle when you already have the stable id, which survives a rename. One of the identity params is required. (one of: handle, user_id; at least one required)", "schema": { "type": "string" } }, { "name": "posts", "in": "query", "required": false, "description": "How many of the fetched recent posts to return and compute the metrics over (1-100, default 25). One call reads one page, which on TikTok is 10 videos, so a larger value returns that page and a `_warnings` note; pass posts_cursor back as cursor for the next page.", "schema": { "type": "integer" }, "example": 25 }, { "name": "cursor", "in": "query", "required": false, "description": "Pass a prior response's posts_cursor to read the next page of posts. Each call is a separate 5-credit call whose metrics cover that page only.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "CSV subset of posts,computed (default both). include=computed omits the raw posts[] array from the response to save payload. The metrics are computed from the same fetched posts either way, so they do not change.", "schema": { "type": "string" } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/profile/full" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "metrics": { "type": "object", "description": "Key performance metrics", "properties": { "total_views": { "type": "integer", "description": "Total view count" }, "total_likes": { "type": "integer", "description": "Total like count" }, "total_comments": { "type": "integer", "description": "Total comment count" }, "engagement_rate": { "type": "number", "description": "Computed engagement rate (0-1)" } } }, "period": { "type": [ "string", "null" ], "description": "Time period for the analytics data" }, "breakdown": { "type": [ "array", "null" ], "description": "Per-item or per-period breakdown", "items": { "type": "object", "description": "Breakdown entry" } }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } } }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/profile/full", "data": { "profile": { "id": "6614519312189947909", "username": "mrbeast", "display_name": "MrBeast", "avatar_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/1e2348ca19d394037718e3b1d3fc2958~tplv-tiktokx-cropcenter:1080:1080.webp?dr=10399&refresh_token=6114ce54&x-expires=1791115200&x-signature=%2BMOUibMYf30LHXW%2FEgd7ElHMHMI%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=2472a6c6&idc=no1a", "bio": "Checkout My New Book!👇", "verified": true, "followers": 142653599, "following": 355, "posts_count": 481, "likes_count": 1505689739, "url": "https://www.tiktok.com/@mrbeast", "private": false, "joined_at": null, "ext": { "business_category": "Public Figure", "bio_link": "http://themostdangerousgames.com" }, "location": "GB" }, "posts": [ { "post": { "id": "7689501576511245598", "url": "https://www.tiktok.com/@mrbeast/video/7689501576511245598", "content": { "text": "“guys don’t laugh” 😭 @Erling Haaland ", "media_urls": "https://v16m.tiktokcdn-us.com/4cb9137a919767e7042103e625abd469/6abffacc/video/tos/useast8/tos-useast8-ve-0068c004-tx2/oIR2I1yuW2IiCmt3iAEsqwxfhNSA2iIBKcqAx0/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=872&ft=gKfIn8s6ogVP12NvnnaqzIxRDUBO63_45SY&mime_type=video_mp4&rc=PDY1O2hkNzk0M2U3OjQ6OUBpamRvNWo5cmo8ZDMzaTczNEAyMTFfMi4zXy0xNi8tMTJiYSNsbS5rMmRzZW9hLS1kMTJzcw%3D%3D&vvpl=1&l=202610021241109E7CBD69C6843C1EB916&btag=e000b0000", "thumbnail_url": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/ogkhxwBxEiqN1rJi0m1C2BQAWI3IqczfAAuiWI~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=8596&refresh_token=7b7c8883&x-expires=1791028800&x-signature=iHdA3tsOlmDyo9aY%2BQya%2FrqnjHo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=useast8&biz_tag=tt_video&s=PUBLISH&sc=cover", "duration_seconds": 6.334 }, "author": { "username": "mrbeast", "display_name": "MrBeast", "avatar_url": "https://example.com/redacted", "verified": true }, "engagement": { "views": 22846963, "likes": 1674980, "comments": 32961, "shares": 38901, "saves": 68320 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2026-09-25T15:53:49.000Z", "ext": { "music_id": "7689501677284117279", "author_id": "6614519312189947909", "author_followers": 142633765, "download_count": 1503, "published_at_epoch": 1790351629, "on_screen_texts": [ "YouTubers locking into a super serious shoot" ] } }, "computed": { "engagement_rate": 0.076458, "language": null, "content_category": "other", "estimated_reach": 27416356 } }, { "post": { "id": "7689134313044184351", "url": "https://www.tiktok.com/@mrbeast/video/7689134313044184351", "content": { "text": "Messing around in the @MrBeast Lab ", "media_urls": "https://v16m.tiktokcdn-us.com/3a4bf492fa1584555fb5ea854a91a732/6abffaff/video/tos/useast8/tos-useast8-ve-0068c002-tx2/o4DpAuViav3EaBcVGKJwoAEg1yrQIRVpBSi5S/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=909&ft=gKfIn8s6ogVP12NvnnaqzIxRDUBO63_45SY&mime_type=video_mp4&rc=ZTk7OjQ7OTQzPGU1NjY1PEBpajM4cWw5cmRuZDMzaTczNEAxMzMtNS80NS4xMWExY19gYSNwXzIuMmRrZm5hLS1kMTJzcw%3D%3D&vvpl=1&l=202610021241109E7CBD69C6843C1EB916&btag=e00088000", "thumbnail_url": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oEdIlJVyFSjDIVNILpAeEQgG1AOqaeWCkaeVvI~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=8596&refresh_token=477f00c6&x-expires=1791028800&x-signature=LLI2EWltc%2FAUreTFEnsGUwMuVQA%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=useast8&biz_tag=tt_video&s=PUBLISH&sc=cover", "duration_seconds": 57.8 }, "author": { "username": "mrbeast", "display_name": "MrBeast", "avatar_url": "https://example.com/redacted", "verified": true }, "engagement": { "views": 4441960, "likes": 272422, "comments": 13896, "shares": 5014, "saves": 12947 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2026-09-24T16:08:22.000Z", "ext": { "music_id": "7689134340546038559", "author_id": "6614519312189947909", "author_followers": 142633765, "download_count": 541, "published_at_epoch": 1790266102 } }, "computed": { "engagement_rate": 0.065586, "language": null, "content_category": "other", "estimated_reach": 5330352 } } ], "computed": { "avg_engagement_rate": 0.1007045, "avg_engagement_rate_by_followers": 0.029072, "posts_per_week": 2.8, "cadence_window_days": 25, "top_post": { "url": "https://www.tiktok.com/@mrbeast/video/7687696606044376350", "engagement_total": 126812149 }, "format_mix": { "video": 10 } }, "posts_cursor": "1788193182304", "legs": [ { "endpoint": "/v1/tiktok/profile", "status": 200, "credits_used": 1, "latency_ms": 1303, "error": null }, { "endpoint": "/v1/tiktok/profile/videos", "status": 200, "credits_used": 1, "latency_ms": 1671, "error": null } ], "_warnings": [ "computed.engagement_rate: author ratio exceeded 1.0 (raw: 10.554867); returned null. A lifetime likes/followers ratio is not a real engagement rate", "posts=25 was requested and 10 came back: one call reads one page of recent posts, and the metrics are computed over that page. Pass posts_cursor back as cursor to read the next page." ] }, "credits_used": 5, "request_id": "req_example000000", "cached": false, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T12:41:14.736Z", "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/tiktok/search/mentions": { "get": { "summary": "Search TikTok videos that mention an account", "description": "Returns TikTok videos by other accounts that mention an account. TikTok has no mentions feed, so each call runs /v1/tiktok/search for `@handle` and for the bare handle and keeps a video only when TikTok links the mention to that account (TikTok often shows a linked mention as the account's display name, so the account id is checked, not just the text), the caption carries the @handle, or it links the profile. The account's own videos are left out unless `include_self=true`, and a video found by both searches appears once. Each row in `data.items` is exactly the row the named search endpoint returns, with its `post` and `computed` blocks, plus `match_kind` (`mention` or `link`). Each row's `post.ext.mentioned_user_ids` lists the accounts TikTok links in it. `since` and `until` keep only rows published inside the window. Send `data.next_cursor` back as `cursor` for the next page; it is null when every search has run out. `data.legs` reports each search: its endpoint, status, rows returned and kept, credits and `request_id`. `data.excluded` counts the rows left out (`unmatched`, `self`, `duplicate`, `outside_window`). Each call is one page of each search, 1 credit each, so at most 2.", "tags": [ "tiktok" ], "operationId": "get_tiktok_search_mentions", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 0, "x-credit-cost-min": 0, "x-credit-cost-max": 2, "x-credit-cost-formula": "Metered, 0-2 credits: each call reads one page of /v1/tiktok/search (1 credit) and /v1/tiktok/search (1 credit), each billed at that endpoint's own price exactly as a direct call is. A page that found nothing or failed costs nothing, and a page served from cache is free. A page is billed when it returned rows, even if none of them carried the mention; data.legs shows each page's charge and data.excluded what was left out.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "The account's username, with or without the @, or its profile URL.", "schema": { "type": "string" }, "example": "nike" }, { "name": "cursor", "in": "query", "required": false, "description": "data.next_cursor from the previous response, sent back verbatim for the next page.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only posts published on or after this date, YYYY-MM-DD (UTC).", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only posts published on or before this date, YYYY-MM-DD (UTC); that whole day is included.", "schema": { "type": "string" } }, { "name": "include_self", "in": "query", "required": false, "description": "When true, also keep posts by the account itself. Default false.", "schema": { "type": "boolean" } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "tiktok" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/tiktok/search/mentions" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "metrics": { "type": "object", "description": "Key performance metrics", "properties": { "total_views": { "type": "integer", "description": "Total view count" }, "total_likes": { "type": "integer", "description": "Total like count" }, "total_comments": { "type": "integer", "description": "Total comment count" }, "engagement_rate": { "type": "number", "description": "Computed engagement rate (0-1)" } } }, "period": { "type": [ "string", "null" ], "description": "Time period for the analytics data" }, "breakdown": { "type": [ "array", "null" ], "description": "Per-item or per-period breakdown", "items": { "type": "object", "description": "Breakdown entry" } }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } } }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached" ] }, "example": { "success": true, "platform": "instagram", "endpoint": "/v1/instagram/engagement", "data": { "engagement_rate_percentages": 38.33, "recent_posts": 12, "followers": 87608035, "comments": 528912, "likes": 33049046, "recent_posts_explanation": "Statistics based on the last 12 posts", "id_user": "2278169415", "username": "mrbeast", "is_private": false, "posts_details": [ { "likes": 5636982, "comments": 69484, "taken_at": 1781457954, "datetime": "2026-06-14 20:25:54", "hours_since_post": 461, "time_ago": "19 days ago", "likes_per_hour": 12228, "comments_per_hour": 151 }, { "likes": 20000768, "comments": 223510, "taken_at": 1732824650, "datetime": "2024-11-28 23:10:50", "hours_since_post": 13971, "time_ago": "2 years ago", "likes_per_hour": 1432, "comments_per_hour": 16 }, { "likes": 929226, "comments": 30633, "taken_at": 1782232475, "datetime": "2026-06-23 19:34:35", "hours_since_post": 246, "time_ago": "10 days ago", "likes_per_hour": 3777, "comments_per_hour": 125 }, { "likes": 487761, "comments": 22482, "taken_at": 1781799425, "datetime": "2026-06-18 19:17:05", "hours_since_post": 366, "time_ago": "15 days ago", "likes_per_hour": 1333, "comments_per_hour": 61 }, { "likes": 712265, "comments": 15716, "taken_at": 1781366405, "datetime": "2026-06-13 19:00:05", "hours_since_post": 487, "time_ago": "20 days ago", "likes_per_hour": 1463, "comments_per_hour": 32 }, { "likes": 1475116, "comments": 35386, "taken_at": 1781277094, "datetime": "2026-06-12 18:11:34", "hours_since_post": 512, "time_ago": "21 days ago", "likes_per_hour": 2881, "comments_per_hour": 69 }, { "likes": 1108220, "comments": 26632, "taken_at": 1780160249, "datetime": "2026-05-30 19:57:29", "hours_since_post": 822, "time_ago": "1 months ago", "likes_per_hour": 1348, "comments_per_hour": 32 }, { "likes": 542948, "comments": 28476, "taken_at": 1779375582, "datetime": "2026-05-21 17:59:42", "hours_since_post": 1040, "time_ago": "1 months ago", "likes_per_hour": 522, "comments_per_hour": 27 }, { "likes": 698514, "comments": 24401, "taken_at": 1779120014, "datetime": "2026-05-18 19:00:14", "hours_since_post": 1111, "time_ago": "2 months ago", "likes_per_hour": 629, "comments_per_hour": 22 }, { "likes": 468000, "comments": 13548, "taken_at": 1778947209, "datetime": "2026-05-16 19:00:09", "hours_since_post": 1159, "time_ago": "2 months ago", "likes_per_hour": 404, "comments_per_hour": 12 }, { "likes": 526594, "comments": 24411, "taken_at": 1777737719, "datetime": "2026-05-02 19:01:59", "hours_since_post": 1495, "time_ago": "2 months ago", "likes_per_hour": 352, "comments_per_hour": 16 }, { "likes": 462652, "comments": 14233, "taken_at": 1777580305, "datetime": "2026-04-30 23:18:25", "hours_since_post": 1538, "time_ago": "2 months ago", "likes_per_hour": 301, "comments_per_hour": 9 } ] }, "credits_used": 5, "credits_remaining": 9999, "request_id": "req-8Kq2ZmR4vT9xLb3P", "cached": false, "redacted": true } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } } }, "x-full-spec": "https://www.socialcrawl.dev/v1/openapi.json" }