{ "openapi": "3.1.0", "info": { "title": "SocialCrawl API: YouTube", "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 YouTube endpoints only (30 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": "youtube", "description": "Youtube endpoints" } ], "paths": { "/youtube/channel": { "get": { "summary": "Get YouTube channel info", "description": "Returns public channel information for a YouTube channel including subscriber count, total video count, total view count, channel description, banner URL, and avatar URL. `author.followers` is YouTube's publicly published subscriber figure. Above 1,000 subscribers YouTube rounds that figure to three significant figures, and `author.ext.followers_approximate` is true. When the channel publishes a contact email in its public description, it is returned as `author.ext.public_email`; otherwise that leaf is null.", "tags": [ "youtube" ], "operationId": "get_youtube_channel", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-socialcrawl-oneOf": [ [ "channelId", "handle", "url" ] ], "parameters": [ { "name": "channelId", "in": "query", "required": false, "description": "YouTube channel ID. Can pass a channelId, handle or url (one of: channelId, handle, url; at least one required)", "schema": { "type": "string" } }, { "name": "handle", "in": "query", "required": false, "description": "YouTube channel handle without the @ symbol (one of: channelId, handle, url; at least one required)", "schema": { "type": "string" }, "example": "MrBeast" }, { "name": "url", "in": "query", "required": false, "description": "YouTube channel URL. Can pass a channelId, handle or url (one of: channelId, handle, url; at least one required)", "schema": { "type": "string" } }, { "name": "hl", "in": "query", "required": false, "description": "Preferred response language for localized text (ISO 639-1, e.g. 'en', 'es', 'fr').", "schema": { "type": "string" } }, { "name": "forUsername", "in": "query", "required": false, "description": "Legacy YouTube username (pre-handle) to look up.", "schema": { "type": "string" } }, { "name": "contact_email", "in": "query", "required": false, "description": "Optional. When 1, also returns author.ext.contact_email: when the bio lists two or more email addresses, the one the creator gives for contacting them personally, copied verbatim from the bio. 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 is unchanged. No extra credits.", "schema": { "type": "string", "enum": [ "1" ] } }, { "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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/channel" }, "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": "youtube", "endpoint": "/v1/youtube/channel", "data": { "author": { "id": "UCX6OQ3DkcsbYNE6H8uQQuVA", "username": "@mrbeast", "display_name": "MrBeast", "avatar_url": "https://yt3.ggpht.com/nxYrc_1_2f77DoBadyxMTmv7ZpRZapHR5jbuYe7PlPd5cIRJxtNNEYyOC0ZsxaDyJJzXrnJiuDE=s800-c-k-c0x00ffffff-no-rj", "bio": "SUBSCRIBE FOR A COOKIE!\nNew MrBeast or MrBeast Gaming video every single Saturday at noon eastern time!\nAccomplishments:\n- Raised $20,000,000 To Plant 20,000,000 Trees\n- Removed 30,000,000 pounds of trash from the ocean\n- Helped 2,000 people walk again\n- Helped 1,000 blind people see\n- Helped 1,000 deaf people hear\n- Built wells in Africa\n- Built and gave away 100 houses\n- Adopted every dog in a shelter (twice)\n- Given millions to charity\n- Started my own snack company Feastables\n- Started my own software company Viewstats\n- Gave away a private island (twice)\n- Gave away 1 million meals\n- I counted to 100k\n- Ran a marathon in the world's largest shoes\n- Survived 50 hours in Antarctica\n- Recreated Squid Game in real life\n- Created the largest competition show with 1000 people (Beast Games)\n- Gave $5,000,000 to one person\n- Raised $40,000,000 To Bring Clean Water To Millions Of People\n- Granted 100+ Dream Wishes for Kids Fighting Cancer\n- Gave Away Another $5,000,000 On Beast Games S2\n", "verified": null, "followers": 519000000, "following": null, "posts_count": 1004, "likes_count": null, "url": "https://www.youtube.com/channel/UCX6OQ3DkcsbYNE6H8uQQuVA", "private": null, "joined_at": "2012-02-20", "ext": { "country": "US", "public_email": null, "followers_approximate": true, "keywords": "mrbeast6000 beast mrbeast Mr.Beast mr", "total_views": 141401695682, "joined_at_timestamp": "2012-02-20T00:43:50Z", "topicCategories": [ "https://en.wikipedia.org/wiki/Entertainment", "https://en.wikipedia.org/wiki/Lifestyle_(sociology)" ], "bannerExternalUrl": "https://yt3.googleusercontent.com/mHMO_eEMp0dPvh0ADwXhPXNYb_GnjSVsLI8biqF1CpxT8OPl7izhNQsDPD3JHhd5y5Mg9GrP", "madeForKids": false, "hiddenSubscriberCount": false, "related_playlists": { "likes": "", "uploads": "UUX6OQ3DkcsbYNE6H8uQQuVA" }, "topic_ids": [ "/m/02jjt", "/m/019_rr" ], "unsubscribed_trailer": "v9QtM6qnG50" } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "gaming", "estimated_reach": null } }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T15:41:11.379Z", "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" } } } } } } }, "/youtube/channel/about": { "get": { "summary": "Get a YouTube channel's contact email and country. Try the 1-credit youtube/channel first: it already carries the email for some channels, and you are charged here only when an address is returned. A first read of an address behind the View email address button can take up to 5 minutes, so set your HTTP timeout to at least 300s; on a 503, retry after the Retry-After seconds", "description": "Returns the contact email a YouTube channel publishes, including the address behind its View email address control (`author.ext.public_email`), and the country listed on the channel (`author.ext.country`, an ISO 3166-1 alpha-2 code, with the English name in `author.ext.country_name`), together with the channel's id, handle, name, subscriber count and video count. `public_email` is only an address the channel publishes on YouTube itself, in its About panel or behind the View email address control; addresses found only on the channel's linked websites or other profiles are not returned. A channel without that control usually answers in a few seconds with `public_email` null, at 0 credits. CHECK THE CHEAP LANE FIRST: `GET /v1/youtube/channel` costs 1 credit and already returns `author.ext.public_email` when the channel writes an address into its public description, which covered 17% of a 12-channel sample. Call this endpoint only when that field came back null; it reads the About tab directly and found an address on a further 58% of the same sample. You are charged ONLY when an address is returned: a channel that publishes none costs 0 credits, and so does a channel that does not exist (404). An address behind the View email address button that has not been read before takes a few minutes to retrieve, and the call waits for it: allow up to 5 minutes before your HTTP client times out. If it is still not ready, the call answers `503 SERVICE_UNAVAILABLE` with `Retry-After: 300` and is not charged, and the same call made after that interval normally returns the address. A 503 is also returned, uncharged, when the channel shows the button but the address could not be retrieved on that call; the error message says which case it is. Do not store `public_email` as empty on a 503.", "tags": [ "youtube" ], "operationId": "get_youtube_channel_about", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "premium", "x-credit-cost": 25, "x-socialcrawl-oneOf": [ [ "channelId", "handle", "url" ] ], "parameters": [ { "name": "channelId", "in": "query", "required": false, "description": "YouTube channel ID. Can pass a channelId, handle or url (one of: channelId, handle, url; at least one required)", "schema": { "type": "string" } }, { "name": "handle", "in": "query", "required": false, "description": "YouTube channel handle without the @ symbol (one of: channelId, handle, url; at least one required)", "schema": { "type": "string" }, "example": "mkbhd" }, { "name": "url", "in": "query", "required": false, "description": "YouTube channel URL. Can pass a channelId, handle or url (one of: channelId, handle, url; at least one required)", "schema": { "type": "string" } }, { "name": "contact_email", "in": "query", "required": false, "description": "Optional. When 1, also returns author.ext.contact_email: when the bio lists two or more email addresses, the one the creator gives for contacting them personally, copied verbatim from the bio. 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 is unchanged. No extra credits.", "schema": { "type": "string", "enum": [ "1" ] } }, { "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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/channel/about" }, "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": "youtube", "endpoint": "/v1/youtube/channel", "data": { "author": { "id": "UCLA_DiR1FfKNvjuUpBHmylQ", "username": "@nasa", "display_name": "NASA", "avatar_url": "https://yt3.ggpht.com/eIf5fNPcIcj9ig-wZBeq4stFy1lgjWTW1nLT5dYlFkHZprZ03QBiMcbpwNMB6XSBjrSFGtAGQg=s800-c-k-c0x00ffffff-no-rj", "bio": "NASA's mission is to pioneer the future in space exploration, scientific discovery, and aeronautics research.\r\n\r\nTo do that, we have worked around the world—and off it—for more than 60 years, searching for answers to fundamental questions about our place in the universe. We're exploring space and discovering Earth. Join us on this exciting and important journey.\n", "verified": null, "followers": 15000000, "following": null, "posts_count": 6139, "likes_count": null, "url": "https://www.youtube.com/channel/UCLA_DiR1FfKNvjuUpBHmylQ", "private": null, "joined_at": "2008-06-03", "ext": { "keywords": "nasa space iss shuttle 50th astronauts planets earth rockets hubble telescopes NASA TV galaxy apollo gemini mercury sta Moon Artemis \"solar system\"", "topicCategories": [ "https://en.wikipedia.org/wiki/Society", "https://en.wikipedia.org/wiki/Knowledge" ], "bannerExternalUrl": "https://yt3.googleusercontent.com/wene-k08O5GIa5h7syMVe6IKiiRiKh6vpajQSUYma01_wG5aMOCqvvAdd2NuljADPuUNPpMkrw", "madeForKids": false, "hiddenSubscriberCount": false, "related_playlists": { "likes": "", "uploads": "UULA_DiR1FfKNvjuUpBHmylQ" }, "topic_ids": [ "/m/098wr", "/m/01k8wb" ], "unsubscribed_trailer": "QONgJurkigk" } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": null } }, "credits_used": 1, "credits_remaining": 9999, "request_id": "req_example000000", "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" } } } } } } }, "/youtube/channel/videos": { "get": { "summary": "List YouTube channel videos", "description": "Returns a list of recent videos published by a YouTube channel. Each video includes title, view count, like count, comment count, duration, thumbnail URL, and publish date. SHORTS: this reads the channel's Videos tab, which is long-form only. Shorts are a separate shelf on YouTube and never appear here (measured 0 of 30 items on 2 channels, 2026-08-11). For a channel's Shorts call `/v1/youtube/channel/shorts` (1 credit, same `channelId`/`handle`); the two sets are disjoint, so calling both and concatenating gives the channel's full catalogue for 2 credits. Every item on both endpoints carries `post.ext.content_type` (`video` or `short`) so the merged list stays separable. Send `include=channel` to add the channel's subscriber count to every row in the same call (1 credit). DATES: `post.published_at` is the exact publish time. A row that ever arrives with only a date derived from a relative label such as \"4 months ago\" is joined to the per-video lookup for the exact second, free; send `exact_dates=false` to keep the supplier's estimate instead, marked by `post.ext.published_precision`. TITLES: the free per-video lookup swaps YouTube's English machine-translated listing title for the creator's own (and description); a title not swapped carries `post.ext.title_maybe_translated: true` (`exact_dates=false` skips the lookup).", "tags": [ "youtube" ], "operationId": "get_youtube_channel_videos", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 2, "x-credit-cost-formula": "1 credit for the page. include=channel adds 1 credit for the single channel lookup the page shares, refunded if the channel could not be read and free when it was looked up recently. 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": [ [ "channelId", "handle" ] ], "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": "channelId", "in": "query", "required": false, "description": "YouTube channel ID (one of: channelId, handle; at least one required)", "schema": { "type": "string" } }, { "name": "handle", "in": "query", "required": false, "description": "YouTube channel handle without the @ symbol (one of: channelId, handle; at least one required)", "schema": { "type": "string" }, "example": "MrBeast" }, { "name": "sort", "in": "query", "required": false, "description": "Sort by latest or popular", "schema": { "type": "string", "enum": [ "latest", "popular" ] } }, { "name": "continuationToken", "in": "query", "required": false, "description": "Continuation token to get more videos. Get 'continuationToken' 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": "string" } }, { "name": "includeExtras", "in": "query", "required": false, "description": "Set to `true` to add the like count and comment count (`post.engagement.likes` / `.comments`) and the video description (`post.ext.description`). For the full per-video detail use /v1/youtube/video. Slows the response slightly.", "schema": { "type": "string" } }, { "name": "is_paid_promotions", "in": "query", "required": false, "description": "Set to 'true' to search YouTube's public paid product placement / sponsorship / endorsement surface: returns normal videos where the creator disclosed a paid promotion.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Set to `channel` (one token only) to add the channel's subscriber count to every row (`post.ext.author_followers`, YouTube's own figure, rounded to three significant figures above 1,000) plus `post.author.display_name`, `.avatar_url` and `post.ext.channel_id` where missing, and the country the channel's owner set as an ISO 3166-1 alpha-2 code on `post.ext.author_country` (null when the channel sets none). Every row is the same channel, so this is one channel lookup for the whole page: 1 credit, refunded if the channel could not be read, and free when the channel was looked up recently. Adds well under a second (never more than 8). Read `data.hydration` for what it did.", "schema": { "type": "string", "enum": [ "channel" ] } }, { "name": "exact_dates", "in": "query", "required": false, "description": "Exact publish dates are on by default and free. A row whose date the upstream derived from a relative label such as \"4 months ago\" (measured up to four months off) is joined to the per-video lookup for its exact publish second, at no extra credit: one lookup per page (two on a page past 50 rows, side by side), adding about 0.2 to 0.7 seconds (never more than 3). The same lookup swaps the listing title, often YouTube's English machine translation, for the creator's own, and `computed.language` follows it; a title not swapped carries `post.ext.title_maybe_translated: true`. Set to `false` to skip the lookup: rows then carry the supplier's date estimate (a day-granular or coarser label truncated to midnight UTC), marked by `post.ext.published_precision` and `post.ext.published_label`, and the listing title, marked by `post.ext.title_maybe_translated`. A row the lookup could not resolve keeps those values and markers, and `_warnings` carries `exact_dates_partial` (some rows) or `exact_dates_unavailable` (none); on `channel/videos`, whose dates are already exact, the warnings are `original_titles_partial` and `original_titles_unavailable`.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "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 `continuationToken` (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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/channel/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": "youtube", "endpoint": "/v1/youtube/channel/videos", "data": { "items": [ { "post": { "id": "v9QtM6qnG50", "url": "https://www.youtube.com/watch?v=v9QtM6qnG50", "content": { "text": "I Built A City To Save Kids From Illegal Labor", "media_urls": null, "thumbnail_url": "https://i.ytimg.com/vi/v9QtM6qnG50/hq720.jpg?sqp=-oaymwEnCNAFEJQDSFryq4qpAxkIARUAAIhCGAHYAQHiAQoIGBACGAY4AUAB&rs=AOn4CLDHC3kCWybW0hDOotcH3B6Q1hT3wg", "duration_seconds": 1143 }, "author": { "username": "user_e32d6a", "display_name": "MrBeast", "avatar_url": "https://example.com/avatars/user_6067d9.png", "verified": null }, "engagement": { "views": 86100683, "likes": 2083951, "comments": 97000, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-19T16:00:01.000Z", "ext": { "content_type": "video", "categoryTitle": "Entertainment", "description": "Huge thanks to the 1 Billion Followers Summit, Mohammed Bin Rashid Global Initiatives, and the Varkey Foundation; the partners who believed in this vision and helped make this village a reality.\n\nClick the link to claim your free Neuro Gum Pack, valued up to $24, at Costco or Walmart here: https://try.gotoaisle.com/neuro-beast\n\nWith gratitude to The Rockefeller Foundation for providing regenerative school meals for the next five years, and for helping build the farm that grows them. https://www.rockefellerfoundation.org\n\nThanks to our friends at Global Energy Alliance, this village now runs on solar — bringing light to every home, market and community space. https://energyalliance.org\n\n190 trees were cut down to bring this village to life. Now we're working with Arbor Day Foundation, our longtime partners, to plant 250 new ones where they'll do the most good.\n\nSUB TO ALL CHANNELS\n   / @mrbeast  \n   / @mrbeast2   \n   / @mrbeastgaming   \n   / @beastreacts   \n   / @beastphilanthropy   \n   / @beastanimations   \n\nNew Merch - https://mrbeast.store\nCheck out Viewstats! - https://www.viewstats.com/\nFor any questions or inquiries regarding this video, please reach out to redacted@example.com\nMusic Provided by https://www.extrememusic.com\n----------------------------------------------------------------\nfollow all of these or i will kick you\n• Facebook -   / mrbeast  \n• Twitter -   / mrbeast  \n• Instagram -   / mrbeast  \n• Im Hiring! - https://www.mrbeastjobs.com/", "channel_id": "UCX6OQ3DkcsbYNE6H8uQQuVA" } }, "computed": { "engagement_rate": 0.02533, "language": null, "content_category": "other", "estimated_reach": 103320820, "vs_creator": { "ratio": 0.72, "metric": "views", "reason": null } } }, { "post": { "id": "gTKS8SAwUzE", "url": "https://www.youtube.com/watch?v=gTKS8SAwUzE", "content": { "text": "I Survived The Most Extreme Places On Earth", "media_urls": null, "thumbnail_url": "https://i.ytimg.com/vi/gTKS8SAwUzE/hq720.jpg?sqp=-oaymwEnCNAFEJQDSFryq4qpAxkIARUAAIhCGAHYAQHiAQoIGBACGAY4AUAB&rs=AOn4CLCinCS-72tR3BbuXhG-OTPNG2SLgw", "duration_seconds": 1408 }, "author": { "username": "user_e32d6a", "display_name": "MrBeast", "avatar_url": "https://example.com/avatars/user_6067d9.png", "verified": null }, "engagement": { "views": 118920840, "likes": 1479890, "comments": 69000, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-05T16:00:01.000Z", "ext": { "content_type": "video", "categoryTitle": "Entertainment", "description": "We raced through some of the most extreme places on Earth to see who could make it to the finish line first!\n\nGemini helped us plan, problem-solve, and take on challenges along the way. Try Gemini here: https://gemini.google.com/app/downloa... GooglePartner\n\nPedialyte always comes in clutch when you need to rehydrate and feel better fast. Grab your favorite Pedialyte flavors on Amazon here https://www.amazon.com/stores/page/79... and use code BEAST40 for 40% off right now. PedialytlePartner\n\nFor anyone wondering about the backpacks we dropped at the end, don't worry! We only ditched them for a second so we could full-send it to the finish line! Our team went right back out and recovered every single piece of gear immediately after to ensure we left the environment as clean as when we got there! ❤️\n\nSUB TO ALL CHANNELS\n   / @mrbeast  \n   / @mrbeast2   \n   / @mrbeastgaming   \n   / @beastreacts   \n   / @beastphilanthropy   \n   / @beastanimations   \n\nNew Merch - https://mrbeast.store\nCheck out Viewstats! - https://www.viewstats.com/\nFor any questions or inquiries regarding this video, please reach out to redacted@example.com\nMusic Provided by https://www.extrememusic.com\n----------------------------------------------------------------\nfollow all of these or i will kick you\n• Facebook -   / mrbeast  \n• Twitter -   / mrbeast  \n• Instagram -   / mrbeast  \n• Im Hiring! - https://www.mrbeastjobs.com/", "channel_id": "UCX6OQ3DkcsbYNE6H8uQQuVA" } }, "computed": { "engagement_rate": 0.013025, "language": null, "content_category": "other", "estimated_reach": 142705008, "vs_creator": { "ratio": 1.38, "metric": "views", "reason": null } } } ], "total": null, "creator_baseline": { "baseline": null, "reason": "fewer_than_eight", "rows_used": 2, "cadence": "omitted" }, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": null, "has_more": false, "page_size": 2, "stopped_at": "since" }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T07:22:55.057Z", "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" } } } } } } }, "/youtube/video": { "get": { "summary": "Get YouTube video details", "description": "Returns detailed information about a specific YouTube video including title, view count, like count, comment count, description, tags, duration, channel info, and publish date.", "tags": [ "youtube" ], "operationId": "get_youtube_video", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full URL of the YouTube video", "schema": { "type": "string" }, "example": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }, { "name": "language", "in": "query", "required": false, "description": "Preferred response language (mapped to Accept-Language header; not guaranteed due to YouTube localization behavior). 2 letter language code, ie 'en', 'es', 'fr' etc.", "schema": { "type": "string" } }, { "name": "hl", "in": "query", "required": false, "description": "Preferred response language for localized text (ISO 639-1, e.g. 'en', 'es', 'fr').", "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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/video" }, "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" } } } } } } }, "/youtube/videos": { "post": { "summary": "Batch get YouTube video details (up to 1000)", "description": "Fetches full details for up to 1000 YouTube videos by id in a single POST request. Each item is the same unified video object as GET /v1/youtube/video. Body: { ids: string[], include_localizations?: boolean }. Metered per 50-id chunk; a request that resolves no videos at all returns 200 with an empty list at 0 credits.", "tags": [ "youtube" ], "operationId": "post_youtube_videos", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "x-credit-cost-min": 5, "x-credit-cost-max": 100, "x-credit-cost-formula": "5 credits per 50-id chunk, so a 50-id batch is 5 credits and the 1,000-id maximum is 100. Batching is what makes this cheap: the same 1,000 videos fetched one at a time through GET /v1/youtube/video cost 1,000 credits. A chunk is charged whether or not every id in it resolves, so there is no per-id refund; a call that resolves nothing at all is refunded in full", "parameters": [ { "name": "hl", "in": "query", "required": false, "description": "Preferred response language for localized text (ISO 639-1, e.g. 'en', 'ko').", "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" } ], "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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/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": "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" } } } } }, "requestBody": { "required": true, "description": "JSON body for youtube/videos. Required: ids.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } }, "include_localizations": { "type": "boolean" } }, "required": [ "ids" ] } } } } } }, "/youtube/channels": { "post": { "summary": "Batch get YouTube channel details (up to 1000)", "description": "Fetches full details for up to 1000 YouTube channels by id in a single POST request. Each item is the unified channel (author) object. Body: { ids: string[], include_localizations?: boolean }. Metered per 50-id chunk; a request that resolves no channels at all returns 200 with an empty list at 0 credits.", "tags": [ "youtube" ], "operationId": "post_youtube_channels", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "x-credit-cost-min": 5, "x-credit-cost-max": 100, "x-credit-cost-formula": "5 credits per 50-id chunk, so a 50-id batch is 5 credits and the 1,000-id maximum is 100. Batching is what makes this cheap: the same 1,000 channels fetched one at a time through GET /v1/youtube/channel cost 1,000 credits. A chunk is charged whether or not every id in it resolves, so there is no per-id refund; a call that resolves nothing at all is refunded in full", "parameters": [ { "name": "hl", "in": "query", "required": false, "description": "Preferred response language for localized text (ISO 639-1, e.g. 'en', 'ko').", "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" } ], "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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/channels" }, "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_0e9522", "username": "user_759369", "display_name": "user_f0b019", "avatar_url": "https://example.com/avatars/user_0ab01c.png", "bio": null, "verified": null, "followers": 4214875, "following": 1, "posts_count": 2341, "likes_count": 62731828, "url": null, "location": null } }, { "author": { "id": "user_d26411", "username": "user_1f51ed", "display_name": "user_1f51ed", "avatar_url": "https://example.com/avatars/user_a81e65.png", "bio": null, "verified": null, "followers": 1780390, "following": 1, "posts_count": 995, "likes_count": 10060260, "url": null, "location": null } }, { "author": { "id": "user_679d13", "username": "user_c5d687", "display_name": "user_8803ea", "avatar_url": "https://example.com/avatars/user_67de4c.png", "bio": null, "verified": null, "followers": 338243, "following": 374, "posts_count": 464, "likes_count": 2140124, "url": null, "location": null } } ], "next_cursor": "30", "total": 30, "dropped": 0 }, "credits_used": 1, "credits_remaining": 9999, "request_id": "req-8Kq2ZmR4vT9xLb3P", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiMzAiLCJwIjoiY3Vyc29yIn0", "has_more": true, "page_size": 30 }, "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" } } } } }, "requestBody": { "required": true, "description": "JSON body for youtube/channels. Required: ids.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } }, "include_localizations": { "type": "boolean" } }, "required": [ "ids" ] } } } } } }, "/youtube/transcripts": { "post": { "summary": "Up to 100 YouTube video ids → one transcript per row, failed ids refunded.", "description": "Batch transcript lookup for LLM corpora. POST a JSON body with an `ids` array of 1-100 BARE 11-character YouTube video ids (full watch URLs are not accepted here: use GET /v1/youtube/video/transcript for a single URL); returns one row per id: the transcript (`format: \"text\"` joins it into one string; `format: \"segments\"` returns `[{start_ms, duration_ms, text}]`), the resolved `language`, and a `status` of ok / not_found / error / deferred: in input order. Optional `language` picks a preferred caption track. Per-id isolation: one caption-less or deleted video never fails the batch: a caption-less video is `not_found` with `ext.reason: \"no_captions\"`, a members-only video (available only to the channel's paying members) is `not_found` with `ext.reason: \"members_only\"`, a deleted/unavailable one is `not_found` with `ext.reason: \"video_gone\"`. Billing is per successful row at 3 credits (the single-transcript registry tier); not_found / errored / deferred rows are refunded, so you pay exactly for the transcripts you got. Never cached. Optionally streams Server-Sent Events when the client sends `Accept: text/event-stream`.", "tags": [ "youtube" ], "operationId": "post_youtube_transcripts", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 3, "x-credit-cost-min": 3, "x-credit-cost-max": 300, "x-credit-cost-formula": "3 credits per successful transcript. Up to 100 ids per call: the call holds ids × 3 up front (a full batch holds 300) and refunds every not_found, errored and deferred row", "parameters": [ { "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" } ], "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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/transcripts" }, "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 …" }, "credits_used": 10, "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" } } } } }, "requestBody": { "required": true, "description": "JSON body for youtube/transcripts. Required: ids.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } }, "language": { "type": "string" }, "format": { "type": "string" } }, "required": [ "ids" ] } } } } } }, "/youtube/video/sponsors": { "get": { "summary": "Detect sponsors of a YouTube video", "description": "Checks a YouTube video for the paid-promotion disclosure and infers likely sponsors/promoted brands from the public description, description links, promo-code text, and transcript. Experimental upstream: sponsor attribution is inferred, with per-sponsor confidence and evidence.", "tags": [ "youtube" ], "operationId": "get_youtube_video_sponsors", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "premium", "x-credit-cost": 10, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full URL of the YouTube video or short", "schema": { "type": "string" }, "example": "https://www.youtube.com/watch?v=AVO0ifle-OU" }, { "name": "language", "in": "query", "required": false, "description": "2 letter language code used for transcript lookup, ie 'en', 'es', 'fr' etc.", "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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/video/sponsors" }, "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": "youtube", "endpoint": "/v1/youtube/video/sponsors", "data": { "video": { "id": "AVO0ifle-OU", "url": "https://www.youtube.com/watch?v=AVO0ifle-OU", "title": "Why You Should Meal Prep Like A Restaurant", "channel": { "id": "UC3vQEjRhwgH2HAOBKwLjxNA", "url": "https://www.youtube.com/@letsKWOOWK", "handle": "letsKWOOWK", "title": "KWOOWK", "thumbnail": "https://yt3.ggpht.com/qmx-SPJT3bDScwd8KC4APZP82cpOoMN1b-kqdl5eASn8pub6jSBxWpq3OO88Wa1fQGWmPVpU=s48-c-k-c0x00ffffff-no-rj" }, "isPaidPromotion": true }, "suspectedSponsors": [ { "name": "user_ef7c54", "website": "betterhelp.com", "confidence": "medium", "evidence": [ { "source": "description_link", "text": "If you're struggling, consider therapy with our sponsor BetterHelp. Click https://betterhelp.com/KWOOWK for a 10% discount on your first month of therapy with a licensed professional specific to your needs. I bought way" } ] } ], "sponsorDetection": { "status": "found", "methods": [ "paid promotion badge", "description" ], "transcriptChecked": false, "transcriptAvailable": false, "note": "Sponsors are inferred from public description, links, promo-code text, and transcript evidence." } }, "credits_used": 10, "request_id": "req_example000000", "cached": false, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T12:50:07.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" } } } } } } }, "/youtube/video/comments": { "get": { "summary": "List YouTube video comments", "description": "Returns a list of comments on a specific YouTube video. Each comment includes the author name, comment text, like count, reply count, and an exact per-second publish timestamp. For a date-window pull (say, the last two years of comments), pass `since` (and optionally `until`): `since` sets `order=newest`, rows arrive newest-first on `comment.published_at` with each next page strictly older and no overlap, rows older than `since` are left off, and the page that reaches one ends the walk (`pagination.stopped_at: \"since\"`). Each page costs what a page costs, so you pay only for the pages walked. One caveat for that walk: the first row of the first page can be the video's pinned comment regardless of `order`; it is out of date order and never ends the walk, so if you walk with `order=newest` yourself, filter rows by timestamp rather than stopping at the first out-of-window row.", "tags": [ "youtube" ], "operationId": "get_youtube_video_comments", "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": "url", "in": "query", "required": true, "description": "Full URL of the YouTube video to fetch comments for", "schema": { "type": "string" }, "example": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }, { "name": "continuationToken", "in": "query", "required": false, "description": "Continuation token to get more comments. Get 'continuationToken' 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": "string" } }, { "name": "order", "in": "query", "required": false, "description": "Order of comments: 'top' (default, YouTube's relevance ranking) or 'newest' (exact newest-first on `comment.published_at`; each next page continues strictly older with no overlap: the lane for date-window and recency pulls).", "schema": { "type": "string", "enum": [ "top", "newest" ] } }, { "name": "searchTerm", "in": "query", "required": false, "description": "Filter comments to those containing this search term.", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "Text format for comment bodies: 'html' (default) or 'plainText'.", "schema": { "type": "string", "enum": [ "html", "plainText" ] } }, { "name": "max_results", "in": "query", "required": false, "description": "Comments per page, 1-100. The default page is already 100, so set this only to shrink a page; out-of-range values are rejected with a free 400 rather than degrading the response.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "channel_id", "in": "query", "required": false, "description": "YouTube channel id to fetch channel-level community comments for (instead of a video's comments).", "schema": { "type": "string" } }, { "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": "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 `continuationToken` (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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/video/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": "youtube", "endpoint": "/v1/youtube/video/comments", "data": { "items": [ { "comment": { "id": "Ugzge340dBgB75hWBm54AaABAg", "url": null, "parent_id": null, "post_id": "dQw4w9WgXcQ", "text": "Sample comment text (redacted).", "author": { "username": "user_607bca", "display_name": "user_607bca", "avatar_url": "https://example.com/avatars/user_b3bde6.png", "verified": null }, "engagement": { "likes": 322497, "replies": 1000 }, "flags": { "pinned": null, "deleted": false }, "published_at": "2025-04-22T19:05:08.000Z", "ext": { "replies_token": "sc2.eyJzIjoiYSIsImMiOiJVZ3pnZTM0MGRCZ0I3NWhXQm01NEFhQUJBZyJ9", "updated_at": "2025-04-22T19:05:08Z", "author_channel_id": "user_0faa89", "author_url": "https://example.com/user_fa30a8", "viewer_rating": "Sample comment text (redacted).", "text_original": "Sample comment text (redacted).", "preview_replies": [ { "id": "Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHE9eIiztxR", "channelId": "user_b70959", "videoId": "dQw4w9WgXcQ", "textDisplay": "Sample comment text (redacted).", "textOriginal": "Sample comment text (redacted).", "parentId": "Ugzge340dBgB75hWBm54AaABAg", "authorDisplayName": "user_a07ce6", "authorProfileImageUrl": "https://example.com/avatars/user_b7fd7d.png", "authorChannelUrl": "https://example.com/user_7ab559", "authorChannelId": { "value": "user_5afaba" }, "canRate": true, "viewerRating": "Sample comment text (redacted).", "likeCount": 7573, "publishedAt": "2025-04-22T19:14:32Z", "updatedAt": "2025-04-22T19:14:32Z" }, { "id": "Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAB_-JmDA", "channelId": "user_b70959", "videoId": "dQw4w9WgXcQ", "textDisplay": "Sample comment text (redacted).", "textOriginal": "Sample comment text (redacted).", "parentId": "Ugzge340dBgB75hWBm54AaABAg", "authorDisplayName": "user_d8b3d6", "authorProfileImageUrl": "https://example.com/avatars/user_2ece01.png", "authorChannelUrl": "https://example.com/user_7a3f35", "authorChannelId": { "value": "user_da87da" }, "canRate": true, "viewerRating": "Sample comment text (redacted).", "likeCount": 3180, "publishedAt": "2025-04-22T19:19:13Z", "updatedAt": "2025-04-22T19:19:13Z" } ] } }, "computed": { "language": "en", "labels": { "sentiment": { "level": 3, "score_0_1": 0.85, "confidence": 0.61 }, "question": { "p": 0.03 }, "purchase_intent": { "p": 0.02 }, "complaint": { "p": 0.04 } } } }, { "comment": { "id": "UgzjClLu_KHsDVWheGx4AaABAg", "url": null, "parent_id": null, "post_id": "dQw4w9WgXcQ", "text": "Sample comment text (redacted).", "author": { "username": "user_f90324", "display_name": "user_f90324", "avatar_url": "https://example.com/avatars/user_191ddb.png", "verified": null }, "engagement": { "likes": 1, "replies": 0 }, "flags": { "pinned": null, "deleted": false }, "published_at": "2026-10-02T15:39:20.000Z", "ext": { "replies_token": "sc2.eyJzIjoiYSIsImMiOiJVZ3pqQ2xMdV9LSHNEVldoZUd4NEFhQUJBZyJ9", "updated_at": "2026-10-02T15:39:20Z", "author_channel_id": "user_121069", "author_url": "https://example.com/user_ec3ca5", "viewer_rating": "Sample comment text (redacted).", "text_original": "Sample comment text (redacted)." } }, "computed": { "language": "en", "labels": { "sentiment": { "level": 3, "score_0_1": 0.76, "confidence": 0.8 }, "question": { "p": 0.02 }, "purchase_intent": { "p": 0.02 }, "complaint": { "p": 0.03 } } } } ], "next_cursor": "sc2.eyJzIjoiYSIsImMiOiJzYzEuZXlKaklqb2lXakpXTUZneU5XeGtNbFo2WkVZNWJXRllTbnBrUXpCMFVUSmtibE5YWkVKVlZscEhUakphVTFRd1NrcFNhMDVPV2pKa1NGRlZSbFJSYkVad1drVnNRMW93U2taYU1WWktZVlZPUWxkVlJrTlRWVnBFVXpKa2JsSXdSa0pWTUVwU1lWVm9TbEZ0WkVKU1YyUldVMWMxY0ZGV2JFSlJhMnhIVVRCc2Nsb3daRUpSVjJ4RldqSTVUbEV3ZEd4YU1UZzFWbFZrUmxNeWF6Rk9SWEJDVWtaV1FsRnNiRUpWVVQwOUlpd2ljeUk2V3lKVlozcG5aVE0wTUdSQ1owSTNOV2hYUW0wMU5FRmhRVUpCWnlJc0lsVm5lbXBEYkV4MVgwdEljMFJXVjJobFIzZzBRV0ZCUWtGbklsMTkifQ", "total": null, "labels": { "presets": [ "sentiment", "question" ], "rows": 2, "labelled": 2, "cached": 1, "skipped": 0, "unjudged": 0, "dropped": 0, "dropped_ids": [], "extra_credits": 0, "methodology_version": "labels/1", "mode": "default", "status": "complete", "pending": 0, "pending_ids": [] }, "label_share": { "policy_version": "share/1", "presets": { "question": { "n": 2, "counted": 0, "abstained": 0, "share": null, "low": 0, "high": 0.575, "receipts": [], "policy_version": "share/1", "too_few": true, "at_cut": 0, "nulls": 0, "low_confidence": 0 }, "purchase_intent": { "n": 2, "counted": 0, "abstained": 0, "share": null, "low": 0, "high": 0.575, "receipts": [], "policy_version": "share/1", "too_few": true, "at_cut": 0, "nulls": 0, "low_confidence": 0 }, "complaint": { "n": 2, "counted": 0, "abstained": 0, "share": null, "low": 0, "high": 0.575, "receipts": [], "policy_version": "share/1", "too_few": true, "at_cut": 0, "nulls": 0, "low_confidence": 0 }, "sentiment": { "positive": { "n": 2, "counted": 2, "abstained": 0, "share": null, "low": 0.425, "high": 1, "receipts": [ { "id": "Ugzge340dBgB75hWBm54AaABAg", "text": "Sample comment text (redacted)." }, { "id": "UgzjClLu_KHsDVWheGx4AaABAg", "text": "Sample comment text (redacted)." } ], "policy_version": "share/1", "too_few": true, "at_cut": 2, "nulls": 0, "low_confidence": 0 }, "neutral": { "n": 2, "counted": 0, "abstained": 0, "share": null, "low": 0, "high": 0.575, "receipts": [], "policy_version": "share/1", "too_few": true, "at_cut": 0, "nulls": 0, "low_confidence": 0 }, "negative": { "n": 2, "counted": 0, "abstained": 0, "share": null, "low": 0, "high": 0.575, "receipts": [], "policy_version": "share/1", "too_few": true, "at_cut": 0, "nulls": 0, "low_confidence": 0 } } } }, "comment_language": { "policy_version": "share/1", "n": 2, "abstained": 0, "judged_by": { "script": 0, "choice": 2 }, "shares": { "en": { "n": 2, "counted": 2, "abstained": 0, "share": null, "low": 0.425, "high": 1, "receipts": [ { "id": "Ugzge340dBgB75hWBm54AaABAg", "text": "Sample comment text (redacted)." }, { "id": "UgzjClLu_KHsDVWheGx4AaABAg", "text": "Sample comment text (redacted)." } ], "policy_version": "share/1", "too_few": true } } }, "comment_recency": { "policy_version": "d09-1", "n": 2, "counted": 2, "abstained": 0, "share_last_24h": 0.5, "share_later_half": null, "too_few": true, "stage": "unknown", "order": "top", "recent_share_is_floor": true, "receipts": [ { "id": "UgzjClLu_KHsDVWheGx4AaABAg", "text": "Sample comment text (redacted)." } ] }, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWVNJc0ltTWlPaUp6WXpFdVpYbEtha2xxYjJsWGFrcFhUVVpuZVU1WGVHdE5iRm8yV2tWWk5XSlhSbGxUYm5CclVYcENNRlZVU210aWJFNVlXa1ZLVmxac2NFaFVha3BoVlRGUmQxTnJjRk5oTURWUFYycEthMU5HUmxaU2JGSlNZa1ZhZDFkclZuTlJNVzkzVTJ0YVlVMVdXa3RaVmxaUFVXeGtWbEpyVGxSV1ZuQkZWWHBLYTJKc1NYZFNhMHBXVFVWd1UxbFdWbTlUYkVaMFdrVktVMVl5VWxkVk1XTXhZMFpHVjJKRlNsSmhNbmhJVlZSQ2MyTnNiM2RhUlVwU1ZqSjRSbGRxU1RWVWJFVjNaRWQ0WVUxVVp6RldiRlpyVW14TmVXRjZSazlTV0VKRFZXdGFWMUZzUm5OaVJVcFdWVlF3T1VscGQybGplVWsyVjNsS1Zsb3pjRzVhVkUwd1RVZFNRMW93U1ROT1YyaFlVVzB3TVU1RlJtaFJWVXBDV25sSmMwbHNWbTVsYlhCRVlrVjRNVmd3ZEVsak1GSlhWakpvYkZJelp6QlJWMFpDVVd0R2JrbHNNVGtpZlEiLCJlIjoieW91dHViZS92aWRlby9jb21tZW50cyIsInAiOiJjb250aW51YXRpb25Ub2tlbiJ9", "has_more": true, "page_size": 2 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T15:41:15.579Z", "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" } } } } } } }, "/youtube/video/comment/replies": { "get": { "summary": "List YouTube comment replies", "description": "Fetches replies to a specific comment on a YouTube video. Each reply includes text content, author details, like count, and publish date. Requires a continuationToken from the Comments endpoint. YouTube's comment model is two levels deep: a top-level comment and one flat list of replies. There is no reply-to-a-reply thread, so reply objects carry no continuation token of their own. When someone answers another reply, YouTube stores it in this same flat list (usually prefixed with an @mention), so paginating this endpoint to exhaustion returns the complete tree. Paginate with the pagination.has_more flag rather than the reply count on the parent comment: that count is YouTube's own tally and can include replies withheld from the public list (held for review, spam-filtered, or from deleted accounts), so an exhausted list is often shorter than it.", "tags": [ "youtube" ], "operationId": "get_youtube_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": "continuationToken", "in": "query", "required": true, "description": "Where to start. Three values work: a top-level comment id (e.g. the `comment.id` of any row from /v1/youtube/video/comments), that row's `comment.ext.replies_token`, or the `pagination.next_cursor` from a previous replies response. A token that is none of these is rejected.", "schema": { "type": "string" }, "example": "Ugzge340dBgB75hWBm54AaABAg" }, { "name": "format", "in": "query", "required": false, "description": "Text format for reply bodies: 'html' (default) or 'plainText'.", "schema": { "type": "string", "enum": [ "html", "plainText" ] } }, { "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": "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 `continuationToken` (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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/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": "youtube", "endpoint": "/v1/youtube/video/comment/replies", "data": { "items": [ { "comment": { "id": "Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHE9eIiztxR", "url": null, "parent_id": "Ugzge340dBgB75hWBm54AaABAg", "post_id": null, "text": "Sample comment text (redacted).", "author": { "username": "user_a07ce6", "display_name": "user_a07ce6", "avatar_url": "https://example.com/avatars/user_b7fd7d.png", "verified": null }, "engagement": { "likes": 7573, "replies": null }, "flags": { "pinned": null, "deleted": false }, "published_at": "2025-04-22T19:14:32.000Z", "ext": { "updated_at": "2025-04-22T19:14:32Z", "author_channel_id": "user_5afaba", "author_url": "https://example.com/user_7ab559", "viewer_rating": "Sample comment text (redacted).", "text_original": "Sample comment text (redacted)." } }, "computed": { "language": "en", "labels": { "sentiment": { "level": 4, "score_0_1": 0.9, "confidence": 0.66 }, "question": { "p": 0.03 }, "purchase_intent": { "p": 0.01 }, "complaint": { "p": 0.11 } } } }, { "comment": { "id": "Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAB_-JmDA", "url": null, "parent_id": "Ugzge340dBgB75hWBm54AaABAg", "post_id": null, "text": "Sample comment text (redacted).", "author": { "username": "user_d8b3d6", "display_name": "user_d8b3d6", "avatar_url": "https://example.com/avatars/user_2ece01.png", "verified": null }, "engagement": { "likes": 3180, "replies": null }, "flags": { "pinned": null, "deleted": false }, "published_at": "2025-04-22T19:19:13.000Z", "ext": { "updated_at": "2025-04-22T19:19:13Z", "author_channel_id": "user_da87da", "author_url": "https://example.com/user_7a3f35", "viewer_rating": "Sample comment text (redacted).", "text_original": "Sample comment text (redacted)." } }, "computed": { "language": "en", "labels": { "sentiment": { "level": 2, "score_0_1": 0.51, "confidence": 0.96 }, "question": { "p": 0.03 }, "purchase_intent": { "p": 0.01 }, "complaint": { "p": 0.03 } } } } ], "next_cursor": "sc2.eyJzIjoiYSIsImMiOiJzYzEuZXlKaklqb2lWV2Q2WjJVek5EQmtRbWRDTnpWb1YwSnROVFJCWVVGQ1FXZDhXakpXTUZneVRuWmlWekZzWW01U1ptUXliREJoUmpsNVdsaENjMkZYVm5wWU0wNHdZMjFXYUdKVE1IUlJNbVJ1VTFka1FsVldXa2RPTWxwVFZEQktTbEpyVGt4UlYyUklVVlZXY0ZKSFpIWlVWVTVNVGpKU2Rsa3dSa2hTVmtKRlRrZDRVVmRWVGxaUlZVcGFVVlpGUFNJc0luTWlPbHNpVldkNloyVXpOREJrUW1kQ056Vm9WMEp0TlRSQllVRkNRV2N1UVVoRk9GOVJRVmRLZURsQlNFVTVaVWxwZW5SNFVpSXNJbFZuZW1kbE16UXdaRUpuUWpjMWFGZENiVFUwUVdGQlFrRm5Ma0ZJUlRoZlVVRlhTbmc1UVVoRlFVSmZMVXB0UkVFaUxDSlZaM3BuWlRNME1HUkNaMEkzTldoWFFtMDFORUZoUVVKQlp5NUJTRVU0WDFGQlYwcDRPVUZJUlVGUFExTnNZVTVPSWl3aVZXZDZaMlV6TkRCa1FtZENOelZvVjBKdE5UUkJZVUZDUVdjdVFVaEZPRjlSUVZkS2VEbEJTRVZCVVhkMGQyUnZXaUlzSWxWbmVtZGxNelF3WkVKblFqYzFhRmRDYlRVMFFXRkJRa0ZuTGtGSVJUaGZVVUZYU25nNVFVaEZRalZwVUVwTVJIQWlMQ0pWWjNwblpUTTBNR1JDWjBJM05XaFhRbTAxTkVGaFFVSkJaeTVCU0VVNFgxRkJWMHA0T1VGSVJVSkpNRGhvVjNGeklpd2lWV2Q2WjJVek5EQmtRbWRDTnpWb1YwSnROVFJCWVVGQ1FXY3VRVWhGT0Y5UlFWZEtlRGxCU0VWQ1ZVeFVOV1pLU2lJc0lsVm5lbWRsTXpRd1pFSm5RamMxYUZkQ2JUVTBRV0ZCUWtGbkxrRklSVGhmVVVGWFNuZzVRVWhGUWxkS1ZHWnZYM0lpTENKVlozcG5aVE0wTUdSQ1owSTNOV2hYUW0wMU5FRmhRVUpCWnk1QlNFVTRYMUZCVjBwNE9VRklSVUpZVmpSb2Ewd3dJaXdpVldkNloyVXpOREJrUW1kQ056Vm9WMEp0TlRSQllVRkNRV2N1UVVoRk9GOVJRVmRLZURsQlNFVkRTa1Z5TURsVmF5SXNJbFZuZW1kbE16UXdaRUpuUWpjMWFGZENiVFUwUVdGQlFrRm5Ma0ZJUlRoZlVVRlhTbmc1UVVoRlExTnhZMmhSWjFvaUxDSlZaM3BuWlRNME1HUkNaMEkzTldoWFFtMDFORUZoUVVKQlp5NUJTRVU0WDFGQlYwcDRPVUZJUlVOeWRsSnhYMHRaSWl3aVZXZDZaMlV6TkRCa1FtZENOelZvVjBKdE5UUkJZVUZDUVdjdVFVaEZPRjlSUVZkS2VEbEJTRVZEZG05SmF5MXhhaUlzSWxWbmVtZGxNelF3WkVKblFqYzFhRmRDYlRVMFFXRkJRa0ZuTGtGSVJUaGZVVUZYU25nNVFVaEZSRXhoTkZrMExUUWlMQ0pWWjNwblpUTTBNR1JDWjBJM05XaFhRbTAxTkVGaFFVSkJaeTVCU0VVNFgxRkJWMHA0T1VGSVJVUmFUbEpFVm5CT0lpd2lWV2Q2WjJVek5EQmtRbWRDTnpWb1YwSnROVFJCWVVGQ1FXY3VRVWhGT0Y5UlFWZEtlRGxCU0VWRVl5MUhkVEk1TXlJc0lsVm5lbWRsTXpRd1pFSm5RamMxYUZkQ2JUVTBRV0ZCUWtGbkxrRklSVGhmVVVGWFNuZzVRVWhGUjFKdWRYZGxRa3NpTENKVlozcG5aVE0wTUdSQ1owSTNOV2hYUW0wMU5FRmhRVUpCWnk1QlNFVTRYMUZCVjBwNE9VRklSVWd6ZG1WTFVtaEVJaXdpVldkNloyVXpOREJrUW1kQ056Vm9WMEp0TlRSQllVRkNRV2N1UVVoRk9GOVJRVmRLZURsQlNFVklORzgyUkVKVk5TSXNJbFZuZW1kbE16UXdaRUpuUWpjMWFGZENiVFUwUVdGQlFrRm5Ma0ZJUlRoZlVVRlhTbmc1UVVoRlNEaFpSRFJMVURVaUxDSlZaM3BuWlRNME1HUkNaMEkzTldoWFFtMDFORUZoUVVKQlp5NUJTRVU0WDFGQlYwcDRPVUZJUlVoUWNHZFJWblZWSWl3aVZXZDZaMlV6TkRCa1FtZENOelZvVjBKdE5UUkJZVUZDUVdjdVFVaEZPRjlSUVZkS2VEbEJTRVZJV2t0UFREbHlReUlzSWxWbmVtZGxNelF3WkVKblFqYzFhRmRDYlRVMFFXRkJRa0ZuTGtGSVJUaGZVVUZYU25nNVFVaEZTRzAzT0VvMVNtNGlMQ0pWWjNwblpUTTBNR1JDWjBJM05XaFhRbTAxTkVGaFFVSkJaeTVCU0VVNFgxRkJWMHA0T1VGSVJVaDNhVzlvZUhvMElpd2lWV2Q2WjJVek5EQmtRbWRDTnpWb1YwSnROVFJCWVVGQ1FXY3VRVWhGT0Y5UlFWZEtlRGxCU0VWS04waFZYMlJOTUNJc0lsVm5lbWRsTXpRd1pFSm5RamMxYUZkQ2JUVTBRV0ZCUWtGbkxrRklSVGhmVVVGWFNuZzVRVWhGU2pnelpWRlZlVU1pTENKVlozcG5aVE0wTUdSQ1owSTNOV2hYUW0wMU5FRmhRVUpCWnk1QlNFVTRYMUZCVjBwNE9VRklSVXBVVWpablRsRkZJaXdpVldkNloyVXpOREJrUW1kQ056Vm9WMEp0TlRSQllVRkNRV2N1UVVoRk9GOVJRVmRLZURsQlNFVktia05CTlZGV2RpSXNJbFZuZW1kbE16UXdaRUpuUWpjMWFGZENiVFUwUVdGQlFrRm5Ma0ZJUlRoZlVVRlhTbmc1UVVoRlMwOXVOemd0V2pZaUxDSlZaM3BuWlRNME1HUkNaMEkzTldoWFFtMDFORUZoUVVKQlp5NUJTRVU0WDFGQlYwcDRPVUZJUlV0eFV6RlBaRzAzSWl3aVZXZDZaMlV6TkRCa1FtZENOelZvVjBKdE5UUkJZVUZDUVdjdVFVaEZPRjlSUVZkS2VEbEJTRVZMZGxGNE9FWmtSQ0lzSWxWbmVtZGxNelF3WkVKblFqYzFhRmRDYlRVMFFXRkJRa0ZuTGtGSVJUaGZVVUZYU25nNVFVaEZUR05XV201emREUWlMQ0pWWjNwblpUTTBNR1JDWjBJM05XaFhRbTAxTkVGaFFVSkJaeTVCU0VVNFgxRkJWMHA0T1VGSVJVeHhRbTFmZVZWQ0lpd2lWV2Q2WjJVek5EQmtRbWRDTnpWb1YwSnROVFJCWVVGQ1FXY3VRVWhGT0Y5UlFWZEtlRGxCU0VWTlFWaGlSV2R4YmlJc0lsVm5lbWRsTXpRd1pFSm5RamMxYUZkQ2JUVTBRV0ZCUWtGbkxrRklSVGhmVVVGWFNuZzVRVWhGVFY5Uk0zUlFZMFlpTENKVlozcG5aVE0wTUdSQ1owSTNOV2hYUW0wMU5FRmhRVUpCWnk1QlNFVTRYMUZCVjBwNE9VRklSVTF1TmpORlVYZFFJaXdpVldkNloyVXpOREJrUW1kQ056Vm9WMEp0TlRSQllVRkNRV2N1UVVoRk9GOVJRVmRLZURsQlNFVk9SVkpsYjJkWVpDSXNJbFZuZW1kbE16UXdaRUpuUWpjMWFGZENiVFUwUVdGQlFrRm5Ma0ZJUlRoZlVVRlhTbmc1UVVoRlRtSTFiSEkwUlc4aUxDSlZaM3BuWlRNME1HUkNaMEkzTldoWFFtMDFORUZoUVVKQlp5NUJTRVU0WDFGQlYwcDRPVUZJUlU5dlJXNUpRM2gzSWl3aVZXZDZaMlV6TkRCa1FtZENOelZvVjBKdE5UUkJZVUZDUVdjdVFVaEZPRjlSUVZkS2VEbEJTRVZRVWtoRFQxRlBaaUlzSWxWbmVtZGxNelF3WkVKblFqYzFhRmRDYlRVMFFXRkJRa0ZuTGtGSVJUaGZVVUZYU25nNVFVaEZVWFIwVWs1SE0wUWlMQ0pWWjNwblpUTTBNR1JDWjBJM05XaFhRbTAxTkVGaFFVSkJaeTVCU0VVNFgxRkJWMHA0T1VGSVJWTXdPSEZqUWtwQ0lpd2lWV2Q2WjJVek5EQmtRbWRDTnpWb1YwSnROVFJCWVVGQ1FXY3VRVWhGT0Y5UlFWZEtlRGxCU0VWVGJ6UlpSWE53UkNJc0lsVm5lbWRsTXpRd1pFSm5RamMxYUZkQ2JUVTBRV0ZCUWtGbkxrRklSVGhmVVVGWFNuZzVRVWhGVTNGTGJIZGxabUVpTENKVlozcG5aVE0wTUdSQ1owSTNOV2hYUW0wMU5FRmhRVUpCWnk1QlNFVTRYMUZCVjBwNE9VRklSVlJDYmw5UmRVZDRJaXdpVldkNloyVXpOREJrUW1kQ056Vm9WMEp0TlRSQllVRkNRV2N1UVVoRk9GOVJRVmRLZURsQlNFVlVUVkJVTm5aMGF5SXNJbFZuZW1kbE16UXdaRUpuUWpjMWFGZENiVFUwUVdGQlFrRm5Ma0ZJUlRoZlVVRlhTbmc1UVVoRlZFNVhhSHBrZDJraUxDSlZaM3BuWlRNME1HUkNaMEkzTldoWFFtMDFORUZoUVVKQlp5NUJTRVU0WDFGQlYwcDRPVUZJUlZSUk4xZ3lObmxTSWl3aVZXZDZaMlV6TkRCa1FtZENOelZvVjBKdE5UUkJZVUZDUVdjdVFVaEZPRjlSUVZkS2VEbEJTRVZVYkdaM1oyZExaeUlzSWxWbmVtZGxNelF3WkVKblFqYzFhRmRDYlRVMFFXRkJRa0ZuTGtGSVJUaGZVVUZYU25nNVFVaEZWSFZmUjFwblQwOGlMQ0pWWjNwblpUTTBNR1JDWjBJM05XaFhRbTAxTkVGaFFVSkJaeTVCU0VVNFgxRkJWMHA0T1VGSVJWVkdSbWsxY2paQklpd2lWV2Q2WjJVek5EQmtRbWRDTnpWb1YwSnROVFJCWVVGQ1FXY3VRVWhGT0Y5UlFWZEtlRGxCU0VWVlRVcERNSFJaV2lJc0lsVm5lbWRsTXpRd1pFSm5RamMxYUZkQ2JUVTBRV0ZCUWtGbkxrRklSVGhmVVVGWFNuZzVRVWhGVlcxclkxbE5WbkFpTENKVlozcG5aVE0wTUdSQ1owSTNOV2hYUW0wMU5FRmhRVUpCWnk1QlNFVTRYMUZCVjBwNE9VRklSVlppU210T2EzbFBJaXdpVldkNloyVXpOREJrUW1kQ056Vm9WMEp0TlRSQllVRkNRV2N1UVVoRk9GOVJRVmRLZURsQlNFVldjRXRPYkZwTlJpSXNJbFZuZW1kbE16UXdaRUpuUWpjMWFGZENiVFUwUVdGQlFrRm5Ma0ZJUlRoZlVVRlhTbmc1UVVoRlZubEpOVlpsY1hRaUxDSlZaM3BuWlRNME1HUkNaMEkzTldoWFFtMDFORUZoUVVKQlp5NUJTRVU0WDFGQlYwcDRPVUZJUlZkek4xTkNUelZqSWl3aVZXZDZaMlV6TkRCa1FtZENOelZvVjBKdE5UUkJZVUZDUVdjdVFVaEZPRjlSUVZkS2VEbEJTRVZZT1U4eFFtcElVU0lzSWxWbmVtZGxNelF3WkVKblFqYzFhRmRDYlRVMFFXRkJRa0ZuTGtGSVJUaGZVVUZYU25nNVFVaEZXR3htY1VZeFlXb2lMQ0pWWjNwblpUTTBNR1JDWjBJM05XaFhRbTAxTkVGaFFVSkJaeTVCU0VVNFgxRkJWMHA0T1VGSVJWaHZkMFZJZVhOWUlpd2lWV2Q2WjJVek5EQmtRbWRDTnpWb1YwSnROVFJCWVVGQ1FXY3VRVWhGT0Y5UlFWZEtlRGxCU0VWWWVEbGthak5NTlNJc0lsVm5lbWRsTXpRd1pFSm5RamMxYUZkQ2JUVTBRV0ZCUWtGbkxrRklSVGhmVVVGWFNuZzVRVWhGV1dkU1l6TlBWMllpTENKVlozcG5aVE0wTUdSQ1owSTNOV2hYUW0wMU5FRmhRVUpCWnk1QlNFVTRYMUZCVjBwNE9VRklSVmxxVDJodWJFRXdJaXdpVldkNloyVXpOREJrUW1kQ056Vm9WMEp0TlRSQllVRkNRV2N1UVVoRk9GOVJRVmRLZURsQlNFVmFWRGc0ZVhCa2RDSXNJbFZuZW1kbE16UXdaRUpuUWpjMWFGZENiVFUwUVdGQlFrRm5Ma0ZJUlRoZlVVRlhTbmc1UVVoRldtaE9hVVJYUm1zaUxDSlZaM3BuWlRNME1HUkNaMEkzTldoWFFtMDFORUZoUVVKQlp5NUJTRVU0WDFGQlYwcDRPVUZJUlZwNVFYUmZUSEZsSWl3aVZXZDZaMlV6TkRCa1FtZENOelZvVjBKdE5UUkJZVUZDUVdjdVFVaEZPRjlSUVZkS2VEbEJTRVZmVFdreWFrWmlieUlzSWxWbmVtZGxNelF3WkVKblFqYzFhRmRDYlRVMFFXRkJRa0ZuTGtGSVJUaGZVVUZYU25nNVFVaEZYMjEwVTBNMFVsb2lMQ0pWWjNwblpUTTBNR1JDWjBJM05XaFhRbTAxTkVGaFFVSkJaeTVCU0VVNFgxRkJWMHA0T1VGSVJXUldWRXRFYW1WNUlpd2lWV2Q2WjJVek5EQmtRbWRDTnpWb1YwSnROVFJCWVVGQ1FXY3VRVWhGT0Y5UlFWZEtlRGxCU0VWa2RVTjVTRGxSY3lJc0lsVm5lbWRsTXpRd1pFSm5RamMxYUZkQ2JUVTBRV0ZCUWtGbkxrRklSVGhmVVVGWFNuZzVRVWhGYVV0ZmFXRXlXSGtpTENKVlozcG5aVE0wTUdSQ1owSTNOV2hYUW0wMU5FRmhRVUpCWnk1QlNFVTRYMUZCVjBwNE9VRklSV3BWTWtGWFZsaHJJaXdpVldkNloyVXpOREJrUW1kQ056Vm9WMEp0TlRSQllVRkNRV2N1UVVoRk9GOVJRVmRLZURsQlNFVnFZMUZYV1Y5a09TSXNJbFZuZW1kbE16UXdaRUpuUWpjMWFGZENiVFUwUVdGQlFrRm5Ma0ZJUlRoZlVVRlhTbmc1UVVoRmExRTNSamxuT0dvaUxDSlZaM3BuWlRNME1HUkNaMEkzTldoWFFtMDFORUZoUVVKQlp5NUJTRVU0WDFGQlYwcDRPVUZJUld0YVozWjRUbE5YSWl3aVZXZDZaMlV6TkRCa1FtZENOelZvVjBKdE5UUkJZVUZDUVdjdVFVaEZPRjlSUVZkS2VEbEJTRVZ0V1hWQlYyZHRhQ0lzSWxWbmVtZGxNelF3WkVKblFqYzFhRmRDYlRVMFFXRkJRa0ZuTGtGSVJUaGZVVUZYU25nNVFVaEZiamhwTFhBd01sOGlMQ0pWWjNwblpUTTBNR1JDWjBJM05XaFhRbTAxTkVGaFFVSkJaeTVCU0VVNFgxRkJWMHA0T1VGSVJYSXlWMEpNUjNsaklpd2lWV2Q2WjJVek5EQmtRbWRDTnpWb1YwSnROVFJCWVVGQ1FXY3VRVWhGT0Y5UlFWZEtlRGxCU0VWeVEzRlVSME5VTnlJc0lsVm5lbWRsTXpRd1pFSm5RamMxYUZkQ2JUVTBRV0ZCUWtGbkxrRklSVGhmVVVGWFNuZzVRVWhGYzNGUVdtMTVTVThpTENKVlozcG5aVE0wTUdSQ1owSTNOV2hYUW0wMU5FRmhRVUpCWnk1QlNFVTRYMUZCVjBwNE9VRklSWE4zVmxoME1rdzVJaXdpVldkNloyVXpOREJrUW1kQ056Vm9WMEp0TlRSQllVRkNRV2N1UVVoRk9GOVJRVmRLZURsQlNFVjBPRXMzYzNsR2VDSXNJbFZuZW1kbE16UXdaRUpuUWpjMWFGZENiVFUwUVdGQlFrRm5Ma0ZJUlRoZlVVRlhTbmc1UVVoRmRHRlpiV3RwZUdraUxDSlZaM3BuWlRNME1HUkNaMEkzTldoWFFtMDFORUZoUVVKQlp5NUJTRVU0WDFGQlYwcDRPVUZJUlhZelgwSnVlRUp2SWl3aVZXZDZaMlV6TkRCa1FtZENOelZvVjBKdE5UUkJZVUZDUVdjdVFVaEZPRjlSUVZkS2VEbEJTRVYyU0VSWWRrVlJVeUlzSWxWbmVtZGxNelF3WkVKblFqYzFhRmRDYlRVMFFXRkJRa0ZuTGtGSVJUaGZVVUZYU25nNVFVaEZkMnN5YWtSak5uTWlMQ0pWWjNwblpUTTBNR1JDWjBJM05XaFhRbTAxTkVGaFFVSkJaeTVCU0VVNFgxRkJWMHA0T1VGSVJYaElYM2xmWldseklpd2lWV2Q2WjJVek5EQmtRbWRDTnpWb1YwSnROVFJCWVVGQ1FXY3VRVWhGT0Y5UlFWZEtlRGxCU0VWNVZGQlJXVkJCWkNJc0lsVm5lbWRsTXpRd1pFSm5RamMxYUZkQ2JUVTBRV0ZCUWtGbkxrRklSVGhmVVVGWFNuZzVRVWhGZVdzMFlreFhURmtpTENKVlozcG5aVE0wTUdSQ1owSTNOV2hYUW0wMU5FRmhRVUpCWnk1QlNFVTRYMUZCVjBwNE9VRklSakZPWHpRM0xXVlRJaXdpVldkNloyVXpOREJrUW1kQ056Vm9WMEp0TlRSQllVRkNRV2N1UVVoRk9GOVJRVmRLZURsQlNFWXhhRzVDU1hsUWNpSXNJbFZuZW1kbE16UXdaRUpuUWpjMWFGZENiVFUwUVdGQlFrRm5Ma0ZJUlRoZlVVRlhTbmc1UVVoR01qTmtTekp5WVVFaUxDSlZaM3BuWlRNME1HUkNaMEkzTldoWFFtMDFORUZoUVVKQlp5NUJTRVU0WDFGQlYwcDRPVUZJUmpKTlRUUlNTR1pYSWl3aVZXZDZaMlV6TkRCa1FtZENOelZvVjBKdE5UUkJZVUZDUVdjdVFVaEZPRjlSUVZkS2VEbEJTRVl6U2xGcWJtTmhjU0lzSWxWbmVtZGxNelF3WkVKblFqYzFhRmRDYlRVMFFXRkJRa0ZuTGtGSVJUaGZVVUZYU25nNVFVaEdORkV6UkZWT2NqQWlMQ0pWWjNwblpUTTBNR1JDWjBJM05XaFhRbTAxTkVGaFFVSkJaeTVCU0VVNFgxRkJWMHA0T1VGSVJqVkRXbWwwVEhwRElpd2lWV2Q2WjJVek5EQmtRbWRDTnpWb1YwSnROVFJCWVVGQ1FXY3VRVWhGT0Y5UlFWZEtlRGxCU0VZMVJHZ3liRjlMVkNJc0lsVm5lbWRsTXpRd1pFSm5RamMxYUZkQ2JUVTBRV0ZCUWtGbkxrRklSVGhmVVVGWFNuZzVRVWhHT1cxU2FUTk5ZVzRpTENKVlozcG5aVE0wTUdSQ1owSTNOV2hYUW0wMU5FRmhRVUpCWnk1QlNFVTRYMUZCVjBwNE9VRklSa0V5ZEVKVFFWRnhJaXdpVldkNloyVXpOREJrUW1kQ056Vm9WMEp0TlRSQllVRkNRV2N1UVVoRk9GOVJRVmRLZURsQlNFWkJPVFZEYkhoclZTSmRmUSJ9", "total": null, "labels": { "presets": [ "sentiment", "question" ], "rows": 100, "labelled": 100, "cached": 100, "skipped": 0, "unjudged": 0, "dropped": 0, "dropped_ids": [], "extra_credits": 0, "methodology_version": "labels/1", "mode": "default", "status": "complete", "pending": 0, "pending_ids": [] }, "label_share": { "policy_version": "share/1", "presets": { "question": { "n": 100, "counted": 1, "abstained": 2, "share": 0.0102, "low": 0.0023, "high": 0.0444, "receipts": [ { "id": "Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEPRHCOQOf", "text": "Sample comment text (redacted)." } ], "policy_version": "share/1", "too_few": false, "at_cut": 2, "nulls": 0, "low_confidence": 2 }, "purchase_intent": { "n": 100, "counted": 0, "abstained": 0, "share": 0, "low": 0, "high": 0.0263, "receipts": [], "policy_version": "share/1", "too_few": false, "at_cut": 0, "nulls": 0, "low_confidence": 0 }, "complaint": { "n": 100, "counted": 1, "abstained": 4, "share": 0.0104, "low": 0.0023, "high": 0.0453, "receipts": [ { "id": "Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEBXV4hkL0", "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted)." } ], "policy_version": "share/1", "too_few": false, "at_cut": 2, "nulls": 0, "low_confidence": 4 }, "sentiment": { "positive": { "n": 100, "counted": 26, "abstained": 24, "share": 0.3421, "low": 0.2594, "high": 0.4357, "receipts": [ { "id": "Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHE9eIiztxR", "text": "Sample comment text (redacted)." }, { "id": "Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAQwtwdoZ", "text": "Sample comment text (redacted)." } ], "policy_version": "share/1", "too_few": false, "at_cut": 26, "nulls": 0, "low_confidence": 24 }, "neutral": { "n": 100, "counted": 33, "abstained": 24, "share": 0.4342, "low": 0.3445, "high": 0.5284, "receipts": [ { "id": "Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAB_-JmDA", "text": "Sample comment text (redacted)." }, { "id": "Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAOCSlaNN", "text": "Sample comment text (redacted)." } ], "policy_version": "share/1", "too_few": false, "at_cut": 33, "nulls": 0, "low_confidence": 24 }, "negative": { "n": 100, "counted": 17, "abstained": 24, "share": 0.2237, "low": 0.1553, "high": 0.311, "receipts": [ { "id": "Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEBXV4hkL0", "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted)." }, { "id": "Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHECJEr09Uk", "text": "Sample comment text (redacted)." } ], "policy_version": "share/1", "too_few": false, "at_cut": 17, "nulls": 0, "low_confidence": 24 } } } }, "comment_language": { "policy_version": "share/1", "n": 100, "abstained": 25, "judged_by": { "script": 1, "choice": 74 }, "shares": { "en": { "n": 100, "counted": 73, "abstained": 25, "share": 0.9733, "low": 0.9226, "high": 0.9911, "receipts": [ { "id": "Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHE9eIiztxR", "text": "Sample comment text (redacted)." }, { "id": "Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAB_-JmDA", "text": "Sample comment text (redacted)." } ], "policy_version": "share/1", "too_few": false }, "es": { "n": 100, "counted": 1, "abstained": 25, "share": 0.0133, "low": 0.003, "high": 0.0576, "receipts": [ { "id": "Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEDc-Gu293", "text": "Sample comment text (redacted)." } ], "policy_version": "share/1", "too_few": false }, "ja": { "n": 100, "counted": 1, "abstained": 25, "share": 0.0133, "low": 0.003, "high": 0.0576, "receipts": [ { "id": "Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHESo4YEspD", "text": "Sample comment text (redacted)." } ], "policy_version": "share/1", "too_few": false } } }, "comment_recency": { "policy_version": "d09-1", "n": 100, "counted": 100, "abstained": 0, "share_last_24h": 0, "share_later_half": null, "too_few": false, "stage": "unknown", "order": "default", "recent_share_is_floor": true, "receipts": [] }, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWVNJc0ltTWlPaUp6WXpFdVpYbEtha2xxYjJsV1YyUTJXakpWZWs1RVFtdFJiV1JEVG5wV2IxWXdTblJPVkZKQ1dWVkdRMUZYWkRoWGFrcFhUVVpuZVZSdVdtbFdla1p6V1cwMVUxcHRVWGxpUkVKb1VtcHNOVmRzYUVOak1rWllWbTV3V1Uwd05IZFpNakZYWVVkS1ZFMUlVbEpOYlZKMVZURmthMUZzVmxkWGEyUlBUV3h3VkZaRVFrdFRiRXB5Vkd0NFVsWXlVa2xWVmxaWFkwWktTRnBJV2xWV1ZUVk5WR3BLVTJSc2EzZFNhMmhUVm10S1JsUnJaRFJWVm1SV1ZHeGFVbFpWY0dGVlZscEdVRk5KYzBsdVRXbFBiSE5wVmxka05sb3lWWHBPUkVKclVXMWtRMDU2Vm05V01FcDBUbFJTUWxsVlJrTlJWMk4xVVZWb1JrOUdPVkpSVm1STFpVUnNRbE5GVlRWYVZXeHdaVzVTTkZWcFNYTkpiRlp1Wlcxa2JFMTZVWGRhUlVwdVVXcGpNV0ZHWkVOaVZGVXdVVmRHUWxGclJtNU1hMFpKVWxSb1psVlZSbGhUYm1jMVVWVm9SbEZWU21aTVZYQjBVa1ZGYVV4RFNsWmFNM0J1V2xSTk1FMUhVa05hTUVrelRsZG9XRkZ0TURGT1JVWm9VVlZLUWxwNU5VSlRSVlUwV0RGR1FsWXdjRFJQVlVaSlVsVkdVRkV4VG5OWlZUVlBTV2wzYVZaWFpEWmFNbFY2VGtSQ2ExRnRaRU5PZWxadlZqQktkRTVVVWtKWlZVWkRVVmRqZFZGVmFFWlBSamxTVVZaa1MyVkViRUpUUlZaQ1ZWaGtNR1F5VW5aWGFVbHpTV3hXYm1WdFpHeE5lbEYzV2tWS2JsRnFZekZoUm1SRFlsUlZNRkZYUmtKUmEwWnVUR3RHU1ZKVWFHWlZWVVpZVTI1bk5WRlZhRVpSYWxad1ZVVndUVkpJUVdsTVEwcFdXak53YmxwVVRUQk5SMUpEV2pCSk0wNVhhRmhSYlRBeFRrVkdhRkZWU2tKYWVUVkNVMFZWTkZneFJrSldNSEEwVDFWR1NWSlZTa3BOUkdodlZqTkdla2xwZDJsV1YyUTJXakpWZWs1RVFtdFJiV1JEVG5wV2IxWXdTblJPVkZKQ1dWVkdRMUZYWTNWUlZXaEdUMFk1VWxGV1pFdGxSR3hDVTBWV1ExWlZlRlZPVjFwTFUybEpjMGxzVm01bGJXUnNUWHBSZDFwRlNtNVJhbU14WVVaa1EySlVWVEJSVjBaQ1VXdEdia3hyUmtsU1ZHaG1WVlZHV0ZOdVp6VlJWV2hHVVd4a1MxWkhXblpZTTBscFRFTktWbG96Y0c1YVZFMHdUVWRTUTFvd1NUTk9WMmhZVVcwd01VNUZSbWhSVlVwQ1duazFRbE5GVlRSWU1VWkNWakJ3TkU5VlJrbFNWVXBaVm1wU2IyRXdkM2RKYVhkcFZsZGtObG95VlhwT1JFSnJVVzFrUTA1NlZtOVdNRXAwVGxSU1FsbFZSa05SVjJOMVVWVm9SazlHT1ZKUlZtUkxaVVJzUWxORlZrUlRhMVo1VFVSc1ZtRjVTWE5KYkZadVpXMWtiRTE2VVhkYVJVcHVVV3BqTVdGR1pFTmlWRlV3VVZkR1FsRnJSbTVNYTBaSlVsUm9abFZWUmxoVGJtYzFVVlZvUmxFeFRuaFpNbWhTV2pGdmFVeERTbFphTTNCdVdsUk5NRTFIVWtOYU1Fa3pUbGRvV0ZGdE1ERk9SVVpvVVZWS1FscDVOVUpUUlZVMFdERkdRbFl3Y0RSUFZVWkpVbFZPZVdSc1NuaFlNSFJhU1dsM2FWWlhaRFphTWxWNlRrUkNhMUZ0WkVOT2VsWnZWakJLZEU1VVVrSlpWVVpEVVZkamRWRlZhRVpQUmpsU1VWWmtTMlZFYkVKVFJWWkVaRzA1U21GNU1YaGhhVWx6U1d4V2JtVnRaR3hOZWxGM1drVktibEZxWXpGaFJtUkRZbFJWTUZGWFJrSlJhMFp1VEd0R1NWSlVhR1pWVlVaWVUyNW5OVkZWYUVaU1JYaG9Ua1pyTUV4VVVXbE1RMHBXV2pOd2JscFVUVEJOUjFKRFdqQkpNMDVYYUZoUmJUQXhUa1ZHYUZGVlNrSmFlVFZDVTBWVk5GZ3hSa0pXTUhBMFQxVkdTVkpWVW1GVWJFcEZWbTVDVDBscGQybFdWMlEyV2pKVmVrNUVRbXRSYldSRFRucFdiMVl3U25ST1ZGSkNXVlZHUTFGWFkzVlJWV2hHVDBZNVVsRldaRXRsUkd4Q1UwVldSVmw1TVVoa1ZFazFUWGxKYzBsc1ZtNWxiV1JzVFhwUmQxcEZTbTVSYW1NeFlVWmtRMkpVVlRCUlYwWkNVV3RHYmt4clJrbFNWR2htVlZWR1dGTnVaelZSVldoR1VqRktkV1JZWkd4UmEzTnBURU5LVmxvemNHNWFWRTB3VFVkU1Exb3dTVE5PVjJoWVVXMHdNVTVGUm1oUlZVcENXbmsxUWxORlZUUllNVVpDVmpCd05FOVZSa2xTVldkNlpHMVdURlZ0YUVWSmFYZHBWbGRrTmxveVZYcE9SRUpyVVcxa1EwNTZWbTlXTUVwMFRsUlNRbGxWUmtOUlYyTjFVVlZvUms5R09WSlJWbVJMWlVSc1FsTkZWa2xPUnpneVVrVktWazVUU1hOSmJGWnVaVzFrYkUxNlVYZGFSVXB1VVdwak1XRkdaRU5pVkZVd1VWZEdRbEZyUm01TWEwWkpVbFJvWmxWVlJsaFRibWMxVVZWb1JsTkVhRnBTUkZKTVZVUlZhVXhEU2xaYU0zQnVXbFJOTUUxSFVrTmFNRWt6VGxkb1dGRnRNREZPUlVab1VWVktRbHA1TlVKVFJWVTBXREZHUWxZd2NEUlBWVVpKVWxWb1VXTkhaRkpXYmxaV1NXbDNhVlpYWkRaYU1sVjZUa1JDYTFGdFpFTk9lbFp2VmpCS2RFNVVVa0paVlVaRFVWZGpkVkZWYUVaUFJqbFNVVlprUzJWRWJFSlRSVlpKVjJ0MFVGUkViSGxSZVVselNXeFdibVZ0Wkd4TmVsRjNXa1ZLYmxGcVl6RmhSbVJEWWxSVk1GRlhSa0pSYTBadVRHdEdTVkpVYUdaVlZVWllVMjVuTlZGVmFFWlRSekF6VDBWdk1WTnROR2xNUTBwV1dqTndibHBVVFRCTlIxSkRXakJKTTA1WGFGaFJiVEF4VGtWR2FGRlZTa0phZVRWQ1UwVlZORmd4UmtKV01IQTBUMVZHU1ZKVmFETmhWemx2WlVodk1FbHBkMmxXVjJRMldqSlZlazVFUW10UmJXUkRUbnBXYjFZd1NuUk9WRkpDV1ZWR1ExRlhZM1ZSVldoR1QwWTVVbEZXWkV0bFJHeENVMFZXUzA0d2FGWllNbEpPVFVOSmMwbHNWbTVsYldSc1RYcFJkMXBGU201UmFtTXhZVVprUTJKVVZUQlJWMFpDVVd0R2JreHJSa2xTVkdobVZWVkdXRk51WnpWUlZXaEdVMnBuZWxwV1JsWmxWVTFwVEVOS1Zsb3pjRzVhVkUwd1RVZFNRMW93U1ROT1YyaFlVVzB3TVU1RlJtaFJWVXBDV25rMVFsTkZWVFJZTVVaQ1ZqQndORTlWUmtsU1ZYQlZWV3BhYmxSc1JrWkphWGRwVmxka05sb3lWWHBPUkVKclVXMWtRMDU2Vm05V01FcDBUbFJTUWxsVlJrTlJWMk4xVVZWb1JrOUdPVkpSVm1STFpVUnNRbE5GVmt0aWEwNUNUbFpHVjJScFNYTkpiRlp1Wlcxa2JFMTZVWGRhUlVwdVVXcGpNV0ZHWkVOaVZGVXdVVmRHUWxGclJtNU1hMFpKVWxSb1psVlZSbGhUYm1jMVVWVm9SbE13T1hWT2VtZDBWMnBaYVV4RFNsWmFNM0J1V2xSTk1FMUhVa05hTUVrelRsZG9XRkZ0TURGT1JVWm9VVlZLUWxwNU5VSlRSVlUwV0RGR1FsWXdjRFJQVlVaSlVsVjBlRlY2UmxCYVJ6QXpTV2wzYVZaWFpEWmFNbFY2VGtSQ2ExRnRaRU5PZWxadlZqQktkRTVVVWtKWlZVWkRVVmRqZFZGVmFFWlBSamxTVVZaa1MyVkViRUpUUlZaTVpHeEdORTlGV210U1EwbHpTV3hXYm1WdFpHeE5lbEYzV2tWS2JsRnFZekZoUm1SRFlsUlZNRkZYUmtKUmEwWnVUR3RHU1ZKVWFHWlZWVVpZVTI1bk5WRlZhRVpVUjA1WFYyMDFlbVJFVVdsTVEwcFdXak53YmxwVVRUQk5SMUpEV2pCSk0wNVhhRmhSYlRBeFRrVkdhRkZWU2tKYWVUVkNVMFZWTkZneFJrSldNSEEwVDFWR1NWSlZlSGhSYlRGbVpWWldRMGxwZDJsV1YyUTJXakpWZWs1RVFtdFJiV1JEVG5wV2IxWXdTblJPVkZKQ1dWVkdRMUZYWTNWUlZXaEdUMFk1VWxGV1pFdGxSR3hDVTBWV1RsRldhR2xTVjJSNFltbEpjMGxzVm01bGJXUnNUWHBSZDFwRlNtNVJhbU14WVVaa1EySlVWVEJSVjBaQ1VXdEdia3hyUmtsU1ZHaG1WVlZHV0ZOdVp6VlJWV2hHVkZZNVVrMHpVbEZaTUZscFRFTktWbG96Y0c1YVZFMHdUVWRTUTFvd1NUTk9WMmhZVVcwd01VNUZSbWhSVlVwQ1duazFRbE5GVlRSWU1VWkNWakJ3TkU5VlJrbFNWVEYxVG1wT1JsVllaRkZKYVhkcFZsZGtObG95VlhwT1JFSnJVVzFrUTA1NlZtOVdNRXAwVGxSU1FsbFZSa05SVjJOMVVWVm9SazlHT1ZKUlZtUkxaVVJzUWxORlZrOVNWa3BzWWpKa1dWcERTWE5KYkZadVpXMWtiRTE2VVhkYVJVcHVVV3BqTVdGR1pFTmlWRlV3VVZkR1FsRnJSbTVNYTBaSlVsUm9abFZWUmxoVGJtYzFVVlZvUmxSdFNURmlTRWt3VWxjNGFVeERTbFphTTNCdVdsUk5NRTFIVWtOYU1Fa3pUbGRvV0ZGdE1ERk9SVVpvVVZWS1FscDVOVUpUUlZVMFdERkdRbFl3Y0RSUFZVWkpVbFU1ZGxKWE5VcFJNMmd6U1dsM2FWWlhaRFphTWxWNlRrUkNhMUZ0WkVOT2VsWnZWakJLZEU1VVVrSlpWVVpEVVZkamRWRlZhRVpQUmpsU1VWWmtTMlZFYkVKVFJWWlJWV3RvUkZReFJsQmFhVWx6U1d4V2JtVnRaR3hOZWxGM1drVktibEZxWXpGaFJtUkRZbFJWTUZGWFJrSlJhMFp1VEd0R1NWSlVhR1pWVlVaWVUyNW5OVkZWYUVaVldGSXdWV3MxU0Uwd1VXbE1RMHBXV2pOd2JscFVUVEJOUjFKRFdqQkpNMDVYYUZoUmJUQXhUa1ZHYUZGVlNrSmFlVFZDVTBWVk5GZ3hSa0pXTUhBMFQxVkdTVkpXVFhkUFNFWnFVV3R3UTBscGQybFdWMlEyV2pKVmVrNUVRbXRSYldSRFRucFdiMVl3U25ST1ZGSkNXVlZHUTFGWFkzVlJWV2hHVDBZNVVsRldaRXRsUkd4Q1UwVldWR0o2VWxwU1dFNTNVa05KYzBsc1ZtNWxiV1JzVFhwUmQxcEZTbTVSYW1NeFlVWmtRMkpVVlRCUlYwWkNVV3RHYmt4clJrbFNWR2htVlZWR1dGTnVaelZSVldoR1ZUTkdUR0pJWkd4YWJVVnBURU5LVmxvemNHNWFWRTB3VFVkU1Exb3dTVE5PVjJoWVVXMHdNVTVGUm1oUlZVcENXbmsxUWxORlZUUllNVVpDVmpCd05FOVZSa2xTVmxKRFltdzVVbVJWWkRSSmFYZHBWbGRrTmxveVZYcE9SRUpyVVcxa1EwNTZWbTlXTUVwMFRsUlNRbGxWUmtOUlYyTjFVVlZvUms5R09WSlJWbVJMWlVSc1FsTkZWbFZVVmtKVlRtNWFNR0Y1U1hOSmJGWnVaVzFrYkUxNlVYZGFSVXB1VVdwak1XRkdaRU5pVkZVd1VWZEdRbEZyUm01TWEwWkpVbFJvWmxWVlJsaFRibWMxVVZWb1JsWkZOVmhoU0hCclpESnJhVXhEU2xaYU0zQnVXbFJOTUUxSFVrTmFNRWt6VGxkb1dGRnRNREZPUlVab1VWVktRbHA1TlVKVFJWVTBXREZHUWxZd2NEUlBWVVpKVWxaU1VrNHhaM2xPYm14VFNXbDNhVlpYWkRaYU1sVjZUa1JDYTFGdFpFTk9lbFp2VmpCS2RFNVVVa0paVlVaRFVWZGpkVkZWYUVaUFJqbFNVVlprUzJWRWJFSlRSVlpWWWtkYU0xb3laRXhhZVVselNXeFdibVZ0Wkd4TmVsRjNXa1ZLYmxGcVl6RmhSbVJEWWxSVk1GRlhSa0pSYTBadVRHdEdTVkpVYUdaVlZVWllVMjVuTlZGVmFFWldTRlptVWpGd2JsUXdPR2xNUTBwV1dqTndibHBVVFRCTlIxSkRXakJKTTA1WGFGaFJiVEF4VGtWR2FGRlZTa0phZVRWQ1UwVlZORmd4UmtKV01IQTBUMVZHU1ZKV1ZrZFNiV3N4WTJwYVFrbHBkMmxXVjJRMldqSlZlazVFUW10UmJXUkRUbnBXYjFZd1NuUk9WRkpDV1ZWR1ExRlhZM1ZSVldoR1QwWTVVbEZXWkV0bFJHeENVMFZXVmxSVmNFUk5TRkphVjJsSmMwbHNWbTVsYldSc1RYcFJkMXBGU201UmFtTXhZVVprUTJKVVZUQlJWMFpDVVd0R2JreHJSa2xTVkdobVZWVkdXRk51WnpWUlZXaEdWbGN4Y2xreGJFNVdia0ZwVEVOS1Zsb3pjRzVhVkUwd1RVZFNRMW93U1ROT1YyaFlVVzB3TVU1RlJtaFJWVXBDV25rMVFsTkZWVFJZTVVaQ1ZqQndORTlWUmtsU1ZscHBVMjEwVDJFemJGQkphWGRwVmxka05sb3lWWHBPUkVKclVXMWtRMDU2Vm05V01FcDBUbFJTUWxsVlJrTlJWMk4xVVZWb1JrOUdPVkpSVm1STFpVUnNRbE5GVmxkalJYUlBZa1p3VGxKcFNYTkpiRlp1Wlcxa2JFMTZVWGRhUlVwdVVXcGpNV0ZHWkVOaVZGVXdVVmRHUWxGclJtNU1hMFpKVWxSb1psVlZSbGhUYm1jMVVWVm9SbFp1YkVwT1ZscHNZMWhSYVV4RFNsWmFNM0J1V2xSTk1FMUhVa05hTUVrelRsZG9XRkZ0TURGT1JVWm9VVlZLUWxwNU5VSlRSVlUwV0RGR1FsWXdjRFJQVlVaSlVsWmtlazR4VGtOVWVsWnFTV2wzYVZaWFpEWmFNbFY2VGtSQ2ExRnRaRU5PZWxadlZqQktkRTVVVWtKWlZVWkRVVmRqZFZGVmFFWlBSamxTVVZaa1MyVkViRUpUUlZaWlQxVTRlRkZ0Y0VsVlUwbHpTV3hXYm1WdFpHeE5lbEYzV2tWS2JsRnFZekZoUm1SRFlsUlZNRkZYUmtKUmEwWnVUR3RHU1ZKVWFHWlZWVVpZVTI1bk5WRlZhRVpYUjNodFkxVlplRmxYYjJsTVEwcFdXak53YmxwVVRUQk5SMUpEV2pCSk0wNVhhRmhSYlRBeFRrVkdhRkZWU2tKYWVUVkNVMFZWTkZneFJrSldNSEEwVDFWR1NWSldhSFprTUZaSlpWaE9XVWxwZDJsV1YyUTJXakpWZWs1RVFtdFJiV1JEVG5wV2IxWXdTblJPVkZKQ1dWVkdRMUZYWTNWUlZXaEdUMFk1VWxGV1pFdGxSR3hDVTBWV1dXVkViR3RoYWs1TlRsTkpjMGxzVm01bGJXUnNUWHBSZDFwRlNtNVJhbU14WVVaa1EySlVWVEJSVjBaQ1VXdEdia3hyUmtsU1ZHaG1WVlZHV0ZOdVp6VlJWV2hHVjFka1UxbDZUbEJXTWxscFRFTktWbG96Y0c1YVZFMHdUVWRTUTFvd1NUTk9WMmhZVVcwd01VNUZSbWhSVlVwQ1duazFRbE5GVlRSWU1VWkNWakJ3TkU5VlJrbFNWbXh4VkRKb2RXSkZSWGRKYVhkcFZsZGtObG95VlhwT1JFSnJVVzFrUTA1NlZtOVdNRXAwVGxSU1FsbFZSa05SVjJOMVVWVm9SazlHT1ZKUlZtUkxaVVJzUWxORlZtRldSR2MwWlZoQ2EyUkRTWE5KYkZadVpXMWtiRTE2VVhkYVJVcHVVV3BqTVdGR1pFTmlWRlV3VVZkR1FsRnJSbTVNYTBaSlVsUm9abFZWUmxoVGJtYzFVVlZvUmxkdGFFOWhWVkpZVW0xemFVeERTbFphTTNCdVdsUk5NRTFIVWtOYU1Fa3pUbGRvV0ZGdE1ERk9SVVpvVVZWS1FscDVOVUpUUlZVMFdERkdRbFl3Y0RSUFZVWkpVbFp3TlZGWVVtWlVTRVpzU1dsM2FWWlhaRFphTWxWNlRrUkNhMUZ0WkVOT2VsWnZWakJLZEU1VVVrSlpWVVpEVVZkamRWRlZhRVpQUmpsU1VWWmtTMlZFYkVKVFJWWm1WRmRyZVdGcldtbGllVWx6U1d4V2JtVnRaR3hOZWxGM1drVktibEZxWXpGaFJtUkRZbFJWTUZGWFJrSlJhMFp1VEd0R1NWSlVhR1pWVlVaWVUyNW5OVkZWYUVaWU1qRXdWVEJOTUZWc2IybE1RMHBXV2pOd2JscFVUVEJOUjFKRFdqQkpNMDVYYUZoUmJUQXhUa1ZHYUZGVlNrSmFlVFZDVTBWVk5GZ3hSa0pXTUhBMFQxVkdTVkpYVWxkV1JYUkZZVzFXTlVscGQybFdWMlEyV2pKVmVrNUVRbXRSYldSRFRucFdiMVl3U25ST1ZGSkNXVlZHUTFGWFkzVlJWV2hHVDBZNVVsRldaRXRsUkd4Q1UwVldhMlJWVGpWVFJHeFNZM2xKYzBsc1ZtNWxiV1JzVFhwUmQxcEZTbTVSYW1NeFlVWmtRMkpVVlRCUlYwWkNVV3RHYmt4clJrbFNWR2htVlZWR1dGTnVaelZSVldoR1lWVjBabUZYUlhsWFNHdHBURU5LVmxvemNHNWFWRTB3VFVkU1Exb3dTVE5PVjJoWVVXMHdNVTVGUm1oUlZVcENXbmsxUWxORlZUUllNVVpDVmpCd05FOVZSa2xTVjNCV1RXdEdXRlpzYUhKSmFYZHBWbGRrTmxveVZYcE9SRUpyVVcxa1EwNTZWbTlXTUVwMFRsUlNRbGxWUmtOUlYyTjFVVlZvUms5R09WSlJWbVJMWlVSc1FsTkZWbkZaTVVaWVYxWTVhMDlUU1hOSmJGWnVaVzFrYkUxNlVYZGFSVXB1VVdwak1XRkdaRU5pVkZVd1VWZEdRbEZyUm01TWEwWkpVbFJvWmxWVlJsaFRibWMxVVZWb1JtRXhSVE5TYW14dVQwZHZhVXhEU2xaYU0zQnVXbFJOTUUxSFVrTmFNRWt6VGxkb1dGRnRNREZPUlVab1VWVktRbHA1TlVKVFJWVTBXREZHUWxZd2NEUlBWVVpKVWxkMFlWb3pXalJVYkU1WVNXbDNhVlpYWkRaYU1sVjZUa1JDYTFGdFpFTk9lbFp2VmpCS2RFNVVVa0paVlVaRFVWZGpkVkZWYUVaUFJqbFNVVlprUzJWRWJFSlRSVlowVjFoV1FsWXlaSFJoUTBselNXeFdibVZ0Wkd4TmVsRjNXa1ZLYmxGcVl6RmhSbVJEWWxSVk1GRlhSa0pSYTBadVRHdEdTVkpVYUdaVlZVWllVMjVuTlZGVmFFWmlhbWh3VEZoQmQwMXNPR2xNUTBwV1dqTndibHBVVFRCTlIxSkRXakJKTTA1WGFGaFJiVEF4VGtWR2FGRlZTa0phZVRWQ1UwVlZORmd4UmtKV01IQTBUMVZHU1ZKWVNYbFdNRXBOVWpOc2FrbHBkMmxXVjJRMldqSlZlazVFUW10UmJXUkRUbnBXYjFZd1NuUk9WRkpDV1ZWR1ExRlhZM1ZSVldoR1QwWTVVbEZXWkV0bFJHeENVMFZXZVZFelJsVlNNRTVWVG5sSmMwbHNWbTVsYldSc1RYcFJkMXBGU201UmFtTXhZVVprUTJKVVZUQlJWMFpDVVd0R2JreHJSa2xTVkdobVZWVkdXRk51WnpWUlZXaEdZek5HVVZkdE1UVlRWVGhwVEVOS1Zsb3pjRzVhVkUwd1RVZFNRMW93U1ROT1YyaFlVVzB3TVU1RlJtaFJWVXBDV25rMVFsTkZWVFJZTVVaQ1ZqQndORTlWUmtsU1dFNHpWbXhvTUUxcmR6VkphWGRwVmxka05sb3lWWHBPUkVKclVXMWtRMDU2Vm05V01FcDBUbFJTUWxsVlJrTlJWMk4xVVZWb1JrOUdPVkpSVm1STFpVUnNRbE5GVmpCUFJYTXpZek5zUjJWRFNYTkpiRlp1Wlcxa2JFMTZVWGRhUlVwdVVXcGpNV0ZHWkVOaVZGVXdVVmRHUWxGclJtNU1hMFpKVWxSb1psVlZSbGhUYm1jMVVWVm9SbVJIUmxwaVYzUndaVWRyYVV4RFNsWmFNM0J1V2xSTk1FMUhVa05hTUVrelRsZG9XRkZ0TURGT1JVWm9VVlZLUWxwNU5VSlRSVlUwV0RGR1FsWXdjRFJQVlVaSlVsaFplbGd3U25WbFJVcDJTV2wzYVZaWFpEWmFNbFY2VGtSQ2ExRnRaRU5PZWxadlZqQktkRTVVVWtKWlZVWkRVVmRqZFZGVmFFWlBSamxTVVZaa1MyVkViRUpUUlZZeVUwVlNXV1JyVmxKVmVVbHpTV3hXYm1WdFpHeE5lbEYzV2tWS2JsRnFZekZoUm1SRFlsUlZNRkZYUmtKUmEwWnVUR3RHU1ZKVWFHWlZWVVpZVTI1bk5WRlZhRVprTW5ONVlXdFNhazV1VFdsTVEwcFdXak53YmxwVVRUQk5SMUpEV2pCSk0wNVhhRmhSYlRBeFRrVkdhRkZWU2tKYWVUVkNVMFZWTkZneFJrSldNSEEwVDFWR1NWSllhRWxZTTJ4bVdsZHNla2xwZDJsV1YyUTJXakpWZWs1RVFtdFJiV1JEVG5wV2IxWXdTblJPVkZKQ1dWVkdRMUZYWTNWUlZXaEdUMFk1VWxGV1pFdGxSR3hDVTBWV05WWkdRbEpYVmtKQ1drTkpjMGxzVm01bGJXUnNUWHBSZDFwRlNtNVJhbU14WVVaa1EySlVWVEJSVjBaQ1VXdEdia3hyUmtsU1ZHaG1WVlZHV0ZOdVp6VlJWV2hHWlZkek1GbHJlRmhVUm10cFRFTktWbG96Y0c1YVZFMHdUVWRTUTFvd1NUTk9WMmhZVVcwd01VNUZSbWhSVlVwQ1duazFRbE5GVlRSWU1VWkNWakJ3TkU5VlJrbFNha1pQV0hwUk0weFhWbFJKYVhkcFZsZGtObG95VlhwT1JFSnJVVzFrUTA1NlZtOVdNRXAwVGxSU1FsbFZSa05SVjJOMVVWVm9SazlHT1ZKUlZtUkxaVVJzUWxORldYaGhSelZEVTFoc1VXTnBTWE5KYkZadVpXMWtiRTE2VVhkYVJVcHVVV3BqTVdGR1pFTmlWRlV3VVZkR1FsRnJSbTVNYTBaSlVsUm9abFZWUmxoVGJtYzFVVlZvUjAxcVRtdFRla3A1V1ZWRmFVeERTbFphTTNCdVdsUk5NRTFIVWtOYU1Fa3pUbGRvV0ZGdE1ERk9SVVpvVVZWS1FscDVOVUpUUlZVMFdERkdRbFl3Y0RSUFZVWkpVbXBLVGxSVVVsTlRSMXBZU1dsM2FWWlhaRFphTWxWNlRrUkNhMUZ0WkVOT2VsWnZWakJLZEU1VVVrSlpWVVpEVVZkamRWRlZhRVpQUmpsU1VWWmtTMlZFYkVKVFJWbDZVMnhHY1dKdFRtaGpVMGx6U1d4V2JtVnRaR3hOZWxGM1drVktibEZxWXpGaFJtUkRZbFJWTUZGWFJrSlJhMFp1VEd0R1NWSlVhR1pWVlVaWVUyNW5OVkZWYUVkT1JrVjZVa1pXVDJOcVFXbE1RMHBXV2pOd2JscFVUVEJOUjFKRFdqQkpNMDVYYUZoUmJUQXhUa1ZHYUZGVlNrSmFlVFZDVTBWVk5GZ3hSa0pXTUhBMFQxVkdTVkpxVmtSWGJXd3dWRWh3UkVscGQybFdWMlEyV2pKVmVrNUVRbXRSYldSRFRucFdiMVl3U25ST1ZGSkNXVlZHUTFGWFkzVlJWV2hHVDBZNVVsRldaRXRsUkd4Q1UwVlpNVkpIWjNsaVJqbE1Wa05KYzBsc1ZtNWxiV1JzVFhwUmQxcEZTbTVSYW1NeFlVWmtRMkpVVlRCUlYwWkNVV3RHYmt4clJrbFNWR2htVlZWR1dGTnVaelZSVldoSFQxY3hVMkZVVGs1WlZ6UnBURU5LVmxvemNHNWFWRTB3VFVkU1Exb3dTVE5PVjJoWVVXMHdNVTVGUm1oUlZVcENXbmsxUWxORlZUUllNVVpDVmpCd05FOVZSa2xTYTBWNVpFVktWRkZXUm5oSmFYZHBWbGRrTmxveVZYcE9SRUpyVVcxa1EwNTZWbTlXTUVwMFRsUlNRbGxWUmtOUlYyTjFVVlZvUms5R09WSlJWbVJMWlVSc1FsTkZXa0pQVkZaRVlraG9jbFpUU21SbVVTSjkiLCJlIjoieW91dHViZS92aWRlby9jb21tZW50L3JlcGxpZXMiLCJwIjoiY29udGludWF0aW9uVG9rZW4ifQ", "has_more": true, "page_size": 100 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T15:41:13.757Z", "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" } } } } } } }, "/youtube/search": { "get": { "summary": "Search YouTube", "description": "Searches YouTube by keyword. Returns matching videos, shorts, and live streams (an untyped search returns all three; `type` scopes to one kind, including channels and playlists). Each video result includes title, URL, thumbnail, view count, publish date, duration, channel info, and badges. DATES: `post.published_at` is exact by default. Without `includeExtras=true` the upstream sends only a date it derived from a relative label such as \"4 months ago\" (measured up to four months off), so every such row is joined to the per-video lookup for its exact publish second, at no extra credit (one lookup per page, about 0.2 to 0.7 seconds). A row the lookup could not resolve keeps the estimate, marked by `post.ext.published_precision`, and `_warnings` says so (`exact_dates_partial` or `exact_dates_unavailable`). Send `exact_dates=false` to skip the lookup and get the supplier's estimate with that marker. Durations for Shorts need `includeExtras=true`. Send `include=engagement` to fill likes, comments, the duration, the exact publish time and the channel id on every video and Short in the same call from the per-video lookup (faster than `includeExtras`, and it keeps the full page), and `include=channel` to add each channel's subscriber count (`post.ext.author_followers`); each costs 1 credit per distinct video or channel filled, at most 5 per page. TITLES: the free per-video lookup swaps YouTube's English machine-translated listing title for the creator's own; a title not swapped carries `post.ext.title_maybe_translated: true` (`exact_dates=false` skips the lookup).", "tags": [ "youtube" ], "operationId": "get_youtube_search", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 19, "x-credit-cost-formula": "1 credit for the page. include=engagement and include=channel each add 1 credit per distinct video or channel filled, at most 5 per join on a page of up to 50 rows, so a page with both is at most 11 credits; ids that could not be filled are refunded, and a repeat of the same call within the cache window costs 0. Relevance against your query (by default, or with relevance=) is free. Adding relevant_to= holds 4 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 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": "query", "in": "query", "required": true, "description": "Search keyword or phrase.", "schema": { "type": "string" }, "example": "javascript tutorial" }, { "name": "uploadDate", "in": "query", "required": false, "description": "Upload date filter. Reliable on its own (no `type`). With `type=shorts`, windows narrower than `this_year` are rejected with a 400 because YouTube returns an empty set for them; `this_year` is accepted but measured to return ~5x fewer unique Shorts across a paginated walk (the upstream re-serves the same items under an advancing `continuationToken`), so the recommended pattern for Shorts recency is no `uploadDate` at all plus `includeExtras=true` and a client-side filter on `post.published_at`. With other `type` values the upstream currently ignores the date filter and may mix content kinds; filter client-side there too. For an EXACT date window rather than these coarse buckets, use `/v1/youtube/search/advanced`, whose `published_after`/`published_before` take RFC-3339 bounds and are genuinely applied.", "schema": { "type": "string", "enum": [ "today", "this_week", "this_month", "this_year" ] } }, { "name": "sortBy", "in": "query", "required": false, "description": "Sort order: relevance or popular. `popular` cannot be combined with `type=shorts` (rejected with a 400. YouTube serves that combination unreliably); it also caps the page at ~20 results. It is also NOT a strict view-count sort: `popular` is a popularity-weighted ranking, and results do not come back in descending view order. Measured on 4 of 4 test keywords: a `new york` search returned 9.5M, then 502.9M, then 66K views in that order. If you need a view-faithful ordering, use `/v1/youtube/search/advanced` with `order=viewCount` and `includeExtras=true`: its ranking leads with the true top results, and the returned `engagement.views` lets you sort the page exactly client-side.", "schema": { "type": "string", "enum": [ "relevance", "popular" ] } }, { "name": "type", "in": "query", "required": false, "description": "Type of content to return. `type=channels` returns one page of about 20 channels, with `has_more: false` and no `next_cursor`, because the provider cannot continue a channel search (measured 25/10/2026); videos, shorts and playlists page normally. NOTE on Shorts results (`type=shorts`, and the Shorts an untyped search mixes in): the Shorts shelf item carries NO channel object upstream (0 of 98 items across 3 keywords on 10/08/2026, 25 of 25 without one on 26/09/2026, raw upstream; `includeExtras=true` does not add it). By default the free per-video lookup that supplies the exact date also fills `post.ext.channel_id` and `post.author.display_name` on those rows, at no extra credit. `post.author.username` (the @handle) and `post.author.avatar_url` stay null on them: send `include=engagement,channel` to fill both and the subscriber count. With `exact_dates=false` no lookup runs and the whole author stays null on Shorts. Video results are unaffected (20/20 carry the full author). `/v1/youtube/search/advanced` also carries `channel_id` on every result at 1 credit, though it has no Shorts filter.", "schema": { "type": "string", "enum": [ "videos", "shorts", "channels", "playlists" ] }, "example": "videos" }, { "name": "duration", "in": "query", "required": false, "description": "Video duration filter. KNOWN UPSTREAM ISSUE: currently not applied by the provider and it can degrade the `type` filter; prefer filtering client-side on `post.content.duration_seconds`.", "schema": { "type": "string", "enum": [ "under_3_min", "between_3_and_20_min", "over_20_min" ] } }, { "name": "region", "in": "query", "required": false, "description": "2-letter country code of the country to put the proxy in.", "schema": { "type": "string" } }, { "name": "continuationToken", "in": "query", "required": false, "description": "Continuation token to get more results. Get `continuationToken` from a previous response. Native upstream cursor param. Send the universal `cursor` instead: the API maps it to this name for you.", "deprecated": true, "schema": { "type": "string" } }, { "name": "includeExtras", "in": "query", "required": false, "description": "Set to `true` to add the like count and comment count (`post.engagement.likes` / `.comments`) and the video description (`post.ext.description`) to each video result. Left off, those three are null. Dates do not need it: `post.published_at` is exact by default either way (see `exact_dates`). For Shorts results it additionally supplies `post.content.duration_seconds`, which those items never carry otherwise. Costs latency and page depth: measured 2387ms and 20 rows without, 9763ms and 16 rows with, on the same query. It does NOT add channel identity to Shorts results (see `type`) and it never adds a subscriber count. For both, send `include=engagement,channel` instead: the video join supplies every row's channel id, and the channel join adds the subscriber count, in this same call. For full per-video details use `/v1/youtube/video`.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Set to `engagement`, `channel`, or both (`engagement,channel`) to fill more of every row in this one call. `engagement` fills `post.engagement.views`, `.likes` and `.comments`, `post.content.duration_seconds`, `post.ext.channel_id` and `post.author.display_name` where the row lacks them, and replaces a date derived from a label such as \"4 months ago\" with the exact publish time (removing `post.ext.published_precision`). `channel` puts the channel's subscriber count on `post.ext.author_followers` (YouTube's own figure, which it rounds to three significant figures above 1,000) and fills the channel's `post.author.display_name`, `.avatar_url` and `.username` where missing. It also adds the country the channel's owner set, as an ISO 3166-1 alpha-2 code on `post.ext.author_country` (null when the channel sets none). Send both to cover rows that arrive without a channel id: the video join supplies it and the channel join then uses it. Each join costs 1 credit per distinct video or channel it filled, and never more than 5 per 50; ids that could not be filled are refunded. Channel and playlist result rows are not videos: the video join skips them. Each join adds 0.2 to 0.7 seconds on a fresh page (one lookup per 50 ids, never more than 8 seconds). Read `data.hydration` for the rows, lookups, credits held and kept, and the time.", "schema": { "type": "string" } }, { "name": "exact_dates", "in": "query", "required": false, "description": "Exact publish dates are on by default and free. A row whose date the upstream derived from a relative label such as \"4 months ago\" (measured up to four months off) is joined to the per-video lookup for its exact publish second, at no extra credit: one lookup per page (two on a page past 50 rows, side by side), adding about 0.2 to 0.7 seconds (never more than 3). The same lookup swaps the listing title, often YouTube's English machine translation, for the creator's own, and `computed.language` follows it; a title not swapped carries `post.ext.title_maybe_translated: true`. Set to `false` to skip the lookup: rows then carry the supplier's date estimate (a day-granular or coarser label truncated to midnight UTC), marked by `post.ext.published_precision` and `post.ext.published_label`, and the listing title, marked by `post.ext.title_maybe_translated`. A row the lookup could not resolve keeps those values and markers, and `_warnings` carries `exact_dates_partial` (some rows) or `exact_dates_unavailable` (none); on `channel/videos`, whose dates are already exact, the warnings are `original_titles_partial` and `original_titles_unavailable`.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "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": "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": "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 `continuationToken` (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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/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": "youtube", "endpoint": "/v1/youtube/search", "data": { "items": [ { "post": { "id": "W6NZfCO5SIk", "url": "https://www.youtube.com/watch?v=W6NZfCO5SIk", "content": { "text": "Sample comment text (redacted).", "media_urls": null, "thumbnail_url": "https://i.ytimg.com/vi/W6NZfCO5SIk/hq720.jpg?sqp=-oaymwEnCNAFEJQDSFryq4qpAxkIARUAAIhCGAHYAQHiAQoIGBACGAY4AUAB&rs=AOn4CLBAlzpYlr0w53HlpbOkOxXqVe137g", "duration_seconds": 2897 }, "author": { "username": "user_25043d", "display_name": "user_5ad2fb", "avatar_url": "https://example.com/avatars/user_429502.png", "verified": null }, "engagement": { "views": 15344643, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2018-04-24T02:37:33.000Z", "ext": { "content_type": "video", "description": null, "channel_id": "UCWv7vMbMWH4-V0ZXdmDpPBA", "published_label": "8 years ago" } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": 18413572, "relevance": { "p": 0.97, "sense": "target", "depth": 2.96, "spam": 0.06 }, "labels": { "sponsored": { "p": 0.03, "disclosed": false, "undisclosed": false, "brand": null }, "intent": { "label": "promoting", "confidence": 0.97, "buyer": false, "seller": 0.84, "fits_offer": null, "urgency": 0.15 }, "niche": { "label": "technology", "confidence": 1, "taxonomy": "sc-niche-v1" } } } }, { "post": { "id": "EerdGm-ehJQ", "url": "https://www.youtube.com/watch?v=EerdGm-ehJQ", "content": { "text": "Sample comment text (redacted).", "media_urls": null, "thumbnail_url": "https://i.ytimg.com/vi/EerdGm-ehJQ/hq720.jpg?sqp=-oaymwEnCNAFEJQDSFryq4qpAxkIARUAAIhCGAHYAQHiAQoIGBACGAY4AUAB&rs=AOn4CLAcTFrvMm74ZMBst8pu_4oMw65A2w", "duration_seconds": 80157 }, "author": { "username": "user_323c9b", "display_name": "user_0595e9", "avatar_url": "https://example.com/avatars/user_ff68e3.png", "verified": null }, "engagement": { "views": 9706193, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2024-05-09T07:28:14.000Z", "ext": { "content_type": "video", "description": null, "channel_id": "UCB6dvaWu0N8uVq2yKsZ5s5g", "published_label": "2 years ago" } }, "computed": { "engagement_rate": null, "language": null, "content_category": "education", "estimated_reach": 11647432, "relevance": { "p": 0.97, "sense": "target", "depth": 2.99, "spam": 0.08 }, "labels": { "sponsored": { "p": 0.03, "disclosed": false, "undisclosed": false, "brand": null }, "intent": { "label": "promoting", "confidence": 0.97, "buyer": false, "seller": 0.8, "fits_offer": null, "urgency": 0.04 }, "niche": { "label": "technology", "confidence": 1, "taxonomy": "sc-niche-v1" } } } } ], "next_cursor": "sc1.eyJjIjoiRXFzREVoTnFZWFpoYzJOeWFYQjBJSFIxZEc5eWFXRnNHcEFEUldkSlVVRlZaMVZuWjBWTVZucGFUMWR0V2tSVWVsWlVVMWQxUTBGUmRFWmFXRXByVWpJd2RGcFhhRXRWV1VsQ1F6SjRiV0pYWTNSU1ZXODBXakl3TUdkblJVeFZSM1JoVkcwNE0xUlZXazlTYldWRFFWRjBjMkV3YkVkU2FsSjBXVlYwVGxaWlNVSkRNMmhNVkROc1JWSklWbEpWTVZwYVoyZEZURkp1VW1oVlZrNXJZMjEzTTFkVlIwTkJVWFJWWVZjNU5GWlVRak5hUlRGU1dqUkpRa013Vm0xUlYzYzFXVzVrTmxac2NISm5aMFZNVTFkb05VMUdSalpoVlhoRldtcERRMEZSZERKaU1IaExUVEJPZEZsVk1IaGpORWxDUXpCV2JHSnVXakpWYTA1cVZtMTNNR2RuUlV4a1YyY3dXakJqTTFSSFNrVlZSa2REUVZGMGIxcEZhM2xaYmtaUVlXNXJlbGswU1VKRE0wcE5WVWhrUkZGWVJqVlJNRVpHWjJkRlRHSlZjRlZhVlZvMFZUSldiMVJyUjBOQlVYUTJZakphVG1KdGVITmhNVnB0VTFsSlFrTXphR3BOTWtabVVUQndiMkZyVG1wblowVk1URmh3VFZKWE9XMVNiVVUxV0RCdFEwRlJkRmxUVlRsTlkxYzVVVk5GVGt0T1RFbENRbWR2UlVOQ1VWRkJaeVV6UkNVelJLQUNCQmlCNE9nWUlndHpaV0Z5WTJndFptVmxaQSUzRCUzRCIsInMiOlsiVzZOWmZDTzVTSWsiLCJFZXJkR20tZWhKUSIsImxmbWctRUo4Z200IiwiUGtaTm83TUZORmciLCJsa0lGRjRtYUtNVSIsInhLT3lERHVRU1ZZIiwiRnRhUVNkcmw3WUEiLCJUaW94VTB3ZE1RZyIsIkVmQWw5Ynd6VlprIiwiSWh5MFF6aUxEZjAiLCJ2b0xKM0NtYU0xcyIsIkVlbnZ2UkNjVmw0IiwidWg0Z0c3TGJEUFEiLCJoZEkyYnFPankzYyIsInJMUHdDQXF5Q0FFIiwibUpUZUZ4U2VoTkEiLCJ6b2ZNbmxsa1ZmSSIsInhjM2FfQ0poakNjIiwiLXpMRW9mRmE5X0kiLCJYSU9McW9QSENKNCJdfQ", "total": null, "relevance": { "mode": "score", "topic_source": "query", "rows": 20, "scored": 20, "cached": 13, "kept": 20, "dropped": 0, "dropped_ids": [], "unjudged": 0, "too_short": 0, "threshold": 0.5, "extra_credits": 0, "methodology_version": "relevance/2", "origin": "default", "pending": 0, "pending_ids": [], "status": "complete" }, "labels": { "presets": [ "sponsored", "intent" ], "rows": 20, "labelled": 20, "cached": 13, "skipped": 0, "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.eyJ2IjoyLCJjIjoic2MxLmV5SmpJam9pUlhGelJFVm9UbkZaV0Zwb1l6Sk9lV0ZZUWpCSlNGSXhaRWM1ZVdGWFJuTkhjRUZFVWxka1NsVlZSbFphTVZadVdqQldUVlp1Y0dGVU1XUjBWMnRTVldWc1dsVlZNV1F4VVRCR1VtUkZXbUZYUlhCeVZXcEpkMlJHY0ZoaFJYUldWMVZzUTFGNlNqUmlWMHBZV1ROU1UxWlhPREJYYWtsM1RVZGtibEpWZUZaU00xSm9Wa2N3TkUweFVsWlhhemxUWWxkV1JGRldSakJqTWtWM1lrVmtVMkZzU2pCWFZsWXdWR3hhV2xOVlNrUk5NbWhOVmtST2MxSldTa2xXYkVwV1RWWndZVm95WkVaVVJrcDFWVzFvVmxack5YSlpNakV6VFRGa1ZsSXdUa0pWV0ZKV1dWWmpOVTVHV2xWUmFrNWhVbFJHVTFkcVVrcFJhMDEzVm0weFVsWXpZekZYVnpWclRteGFjMk5JU201YU1GWk5WVEZrYjA1Vk1VZFNhbHBvVmxob1JsZHRjRVJSTUVaU1pFUkthVTFJYUV4VVZFSlBaRVpzVmsxSWFHcE9SV3hEVVhwQ1YySkhTblZYYWtwV1lUQTFjVlp0TVROTlIyUnVVbFY0YTFZeVkzZFhha0pxVFRGU1NGTnJWbFpTYTJSRVVWWkdNR0l4Y0VaaE0yeGFZbXRhVVZsWE5YSmxiR3N3VTFWS1JFMHdjRTVXVldoclVrWkdXVkpxVmxKTlJWcEhXakprUmxSSFNsWmpSbFpoVmxadk1GWlVTbGRpTVZKeVVqQk9RbFZZVVRKWmFrcGhWRzFLZEdWSVRtaE5WbkIwVlRGc1NsRnJUWHBoUjNCT1RXdGFiVlZVUW5kaU1rWnlWRzF3Ymxvd1ZrMVVSbWgzVkZaS1dFOVhNVk5pVlZVeFYwUkNkRkV3UmxKa1JteFVWbFJzVGxreFl6VlZWazVHVkd0MFQxUkZiRU5SYldSMlVsVk9RMVZXUmtKYWVWVjZVa05WZWxKTFFVTkNRbWxDTkU5bldVbG5kSHBhVjBaNVdUSm5kRnB0Vm14YVFTVXpSQ1V6UkNJc0luTWlPbHNpVnpaT1dtWkRUelZUU1dzaUxDSkZaWEprUjIwdFpXaEtVU0lzSW14bWJXY3RSVW80WjIwMElpd2lVR3RhVG04M1RVWk9SbWNpTENKc2EwbEdSalJ0WVV0TlZTSXNJbmhMVDNsRVJIVlJVMVpaSWl3aVJuUmhVVk5rY213M1dVRWlMQ0pVYVc5NFZUQjNaRTFSWnlJc0lrVm1RV3c1WW5kNlZscHJJaXdpU1doNU1GRjZhVXhFWmpBaUxDSjJiMHhLTTBOdFlVMHhjeUlzSWtWbGJuWjJVa05qVm13MElpd2lkV2cwWjBjM1RHSkVVRkVpTENKb1pFa3lZbkZQYW5rell5SXNJbkpNVUhkRFFYRjVRMEZGSWl3aWJVcFVaVVo0VTJWb1RrRWlMQ0o2YjJaTmJteHNhMVptU1NJc0luaGpNMkZmUTBwb2FrTmpJaXdpTFhwTVJXOW1SbUU1WDBraUxDSllTVTlNY1c5UVNFTktOQ0pkZlEiLCJlIjoieW91dHViZS9zZWFyY2giLCJwIjoiY29udGludWF0aW9uVG9rZW4ifQ", "has_more": true, "page_size": 20 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T07:23:05.586Z", "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" } } } } } } }, "/youtube/channel/shorts": { "get": { "summary": "List YouTube channel shorts", "description": "Returns a list of YouTube Shorts published by a channel, read from the channel's own Shorts shelf. Each short includes view count, like count, comment count, title, thumbnail, duration and exact publish date (measured 100% coverage on all six across 96 items, 2026-08-11), and unlike `/v1/youtube/search?type=shorts` every item carries channel identity. This is the Shorts complement to `/v1/youtube/channel/videos`, which is long-form only: the two sets are disjoint, so calling both and concatenating gives the channel's full catalogue for 2 credits. Every item carries `post.ext.content_type` (`short` here, `video` there) so the merged list stays separable. Send `include=channel` to add the channel's subscriber count, name, avatar and channel id to every row in the same call (1 credit). TITLES: the free per-video lookup swaps YouTube's English machine-translated listing title for the creator's own; a title not swapped carries `post.ext.title_maybe_translated: true` (`exact_dates=false` skips the lookup).", "tags": [ "youtube" ], "operationId": "get_youtube_channel_shorts", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 2, "x-credit-cost-formula": "1 credit for the page. include=channel adds 1 credit for the single channel lookup the page shares, refunded if the channel could not be read and free when it was looked up recently. 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": [ [ "channelId", "handle" ] ], "parameters": [ { "name": "since", "in": "query", "required": false, "description": "Only shorts published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Older shorts 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 shorts 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 short you already hold. The page stops just before it: that short and everything after it are left off, `next_cursor` is not returned, and `pagination.stopped_at` is `known_id`. A pinned short 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": "YouTube channel handle without the @ symbol (one of: channelId, handle; at least one required)", "schema": { "type": "string" }, "example": "MrBeast" }, { "name": "channelId", "in": "query", "required": false, "description": "Can pass channelId or handle (one of: channelId, handle; at least one required)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort by newest (descending publish date) or popular (descending view count). Both orderings are genuinely applied, unlike `/v1/youtube/search`'s `popular`, which is a popularity-weighted ranking rather than a view sort.", "schema": { "type": "string", "enum": [ "newest", "popular" ] } }, { "name": "continuationToken", "in": "query", "required": false, "description": "Continuation token to get more videos. Get 'continuationToken' 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": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Set to `channel` (one token only) to add the channel's subscriber count to every row (`post.ext.author_followers`, YouTube's own figure, rounded to three significant figures above 1,000) plus `post.author.display_name`, `.avatar_url` and `post.ext.channel_id` where missing, and the country the channel's owner set as an ISO 3166-1 alpha-2 code on `post.ext.author_country` (null when the channel sets none). Every row is the same channel, so this is one channel lookup for the whole page: 1 credit, refunded if the channel could not be read, and free when the channel was looked up recently. Adds well under a second (never more than 8). Read `data.hydration` for what it did.", "schema": { "type": "string", "enum": [ "channel" ] } }, { "name": "exact_dates", "in": "query", "required": false, "description": "On by default and free: every row is joined to the per-video lookup, one lookup per page (two on a page past 50 rows, side by side), adding about 0.2 to 0.7 seconds (never more than 3). The same lookup swaps the listing title, often YouTube's English machine translation, for the creator's own, and `computed.language` follows it; a title not swapped carries `post.ext.title_maybe_translated: true`. Set to `false` to skip the lookup and keep the listing title, marked by `post.ext.title_maybe_translated`. A row the lookup could not resolve keeps the listing title and the marker, and `_warnings` carries `original_titles_partial` (some rows) or `original_titles_unavailable` (none). The dates on this endpoint are exact either way.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "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 `continuationToken` (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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/channel/shorts" }, "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": "youtube", "endpoint": "/v1/youtube/channel/shorts", "data": { "items": [ { "post": { "id": "CEJXqm2eiJ0", "url": "https://www.youtube.com/watch?v=CEJXqm2eiJ0", "content": { "text": "What’s Inside My Briefcase?", "media_urls": null, "thumbnail_url": "https://img.youtube.com/vi/CEJXqm2eiJ0/maxresdefault.jpg", "duration_seconds": 40 }, "author": { "username": "user_e32d6a", "display_name": null, "avatar_url": null, "verified": null }, "engagement": { "views": 28866975, "likes": 580691, "comments": 13000, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-27T16:00:14.000Z", "ext": { "content_type": "short", "categoryTitle": "Entertainment", "description": null } }, "computed": { "engagement_rate": 0.020566, "language": null, "content_category": "other", "estimated_reach": 34640370, "vs_creator": { "ratio": 1.32, "metric": "views", "reason": null } } }, { "post": { "id": "T_SMf9j50uc", "url": "https://www.youtube.com/watch?v=T_SMf9j50uc", "content": { "text": "Can We Build an Entire Village?", "media_urls": null, "thumbnail_url": "https://img.youtube.com/vi/T_SMf9j50uc/maxresdefault.jpg", "duration_seconds": 39 }, "author": { "username": "user_e32d6a", "display_name": null, "avatar_url": null, "verified": null }, "engagement": { "views": 21817759, "likes": 788700, "comments": 16000, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-18T16:00:01.000Z", "ext": { "content_type": "short", "categoryTitle": "Entertainment", "description": null } }, "computed": { "engagement_rate": 0.036883, "language": null, "content_category": "other", "estimated_reach": 26181311, "vs_creator": { "ratio": 0.76, "metric": "views", "reason": null } } } ], "total": null, "creator_baseline": { "baseline": null, "reason": "fewer_than_eight", "rows_used": 2, "cadence": "omitted" }, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": null, "has_more": false, "page_size": 2, "stopped_at": "since" }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T07:29:58.564Z", "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" } } } } } } }, "/youtube/community-post": { "get": { "summary": "Get YouTube community post", "description": "Returns details of a YouTube community post including text content, like count, comment count, images, and author info.", "tags": [ "youtube" ], "operationId": "get_youtube_community_post", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full URL of the YouTube community post", "schema": { "type": "string" }, "example": "https://www.youtube.com/post/Ugkxvj2KoApYAXoqLWnKVr6zZe5JjeHrQeP8" }, { "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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/community-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" } } } } } } }, "/youtube/playlist": { "get": { "summary": "Get YouTube playlist", "description": "Returns the videos in a YouTube playlist in playlist order: video id, title, thumbnail, the video's own channel (`post.author.display_name`, `post.ext.channel_id`) and its publish date, plus a `cursor` for the next page. YouTube's playlist listing carries no view, like or comment counts and no duration, so on a plain call those are null. Send `include=engagement` and every row is joined, in the same call, to the per-video lookup that carries them, and `include=channel` adds each video's channel subscriber count; each costs 1 credit per distinct video or channel filled, at most 5 per page. This endpoint and `/v1/youtube/playlist/items` return the same rows from the same source; this one additionally has a second source behind it, so prefer it when availability matters.", "tags": [ "youtube" ], "operationId": "get_youtube_playlist", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 11, "x-credit-cost-formula": "1 credit for the page. include=engagement and include=channel each add 1 credit per distinct video or channel filled, at most 5 per join on a page of up to 50 rows, so a page with both is at most 11 credits; ids that could not be filled are refunded, and a repeat of the same call within the cache window costs 0. 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": "playlist_id", "in": "query", "required": true, "description": "YouTube playlist ID", "schema": { "type": "string" }, "example": "PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf" }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous response: fetches the next page.", "schema": { "type": "string" } }, { "name": "channel_id", "in": "query", "required": false, "description": "YouTube channel id: pages that channel's uploads instead of a playlist.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Set to `engagement`, `channel`, or both (`engagement,channel`) to fill more of every row in this one call. `engagement` fills `post.engagement.views`, `.likes` and `.comments`, `post.content.duration_seconds`, `post.ext.channel_id` and `post.author.display_name` where the row lacks them, and replaces a date derived from a label such as \"4 months ago\" with the exact publish time (removing `post.ext.published_precision`). `channel` puts the channel's subscriber count on `post.ext.author_followers` (YouTube's own figure, which it rounds to three significant figures above 1,000) and fills the channel's `post.author.display_name`, `.avatar_url` and `.username` where missing. It also adds the country the channel's owner set, as an ISO 3166-1 alpha-2 code on `post.ext.author_country` (null when the channel sets none). Send both to cover rows that arrive without a channel id: the video join supplies it and the channel join then uses it. Each join costs 1 credit per distinct video or channel it filled, and never more than 5 per 50; ids that could not be filled are refunded. Each join adds 0.2 to 0.7 seconds on a fresh page (one lookup per 50 ids, never more than 8 seconds). Read `data.hydration` for the rows, lookups, credits held and kept, and the time.", "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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/playlist" }, "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": "youtube", "endpoint": "/v1/youtube/playlist", "data": { "items": [ { "post": { "id": "0VH1Lim8gL8", "url": "https://www.youtube.com/watch?v=0VH1Lim8gL8", "content": { "text": "Sample comment text (redacted).", "media_urls": null, "thumbnail_url": "https://i.ytimg.com/vi/0VH1Lim8gL8/hqdefault.jpg", "duration_seconds": null }, "author": { "username": null, "display_name": "user_1cfeef", "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": "2020-01-10T16:04:31.000Z", "ext": { "position": 0, "playlistId": "PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf", "videoOwnerChannelId": "UCSHZKyawb77ixDdsGog4iWA", "videoPublishedAt": "2020-01-10T16:04:31Z", "description": "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).", "playlist_item_id": "UExyQVh0bUVyWmdPZWlLbTRzZ05Pa25Hdk5qYnk5ZWZkZi4yMUQyQTQzMjRDNzMyQTMy", "playlist_owner_channel_id": "UCSHZKyawb77ixDdsGog4iWA", "playlist_owner_title": "Lex Fridman", "channel_id": "UCSHZKyawb77ixDdsGog4iWA" } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": null } }, { "post": { "id": "O5xeyoRL95U", "url": "https://www.youtube.com/watch?v=O5xeyoRL95U", "content": { "text": "Sample comment text (redacted).", "media_urls": null, "thumbnail_url": "https://i.ytimg.com/vi/O5xeyoRL95U/hqdefault.jpg", "duration_seconds": null }, "author": { "username": null, "display_name": "user_1cfeef", "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": "2019-01-11T16:47:40.000Z", "ext": { "position": 1, "playlistId": "PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf", "videoOwnerChannelId": "UCSHZKyawb77ixDdsGog4iWA", "videoPublishedAt": "2019-01-11T16:47:40Z", "description": "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).", "playlist_item_id": "UExyQVh0bUVyWmdPZWlLbTRzZ05Pa25Hdk5qYnk5ZWZkZi4zMDg5MkQ5MEVDMEM1NTg2", "playlist_owner_channel_id": "UCSHZKyawb77ixDdsGog4iWA", "playlist_owner_title": "Lex Fridman", "channel_id": "UCSHZKyawb77ixDdsGog4iWA" } }, "computed": { "engagement_rate": null, "language": null, "content_category": "other", "estimated_reach": null } } ], "total": 2, "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-02T07:29:59.833Z", "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" } } } } } } }, "/youtube/search/hashtag": { "get": { "summary": "Search YouTube by hashtag", "description": "Searches YouTube for videos under a specific hashtag. Returns matching videos with view counts, channel info, and publish dates. DATES: the upstream sends only a date derived from a relative label such as \"3 weeks ago\" (or none), so by default every such row is joined to the per-video lookup for its exact publish second, at no extra credit (one lookup per page); send `exact_dates=false` to keep the estimate instead, marked by `post.ext.published_precision`. ROWS ARE UNEVEN, from the upstream: a large minority carry only id, URL, title and view count. The same free per-video lookup that fixes the dates gives those rows their channel id (`post.ext.channel_id`) and channel name (`post.author.display_name`), but `post.content.duration_seconds`, `post.content.thumbnail_url`, `post.author.username` and `post.author.avatar_url` stay null on them. With `exact_dates=false` no lookup runs, so the channel stays null too. That is a property of YouTube's hashtag shelf, not of your query. Send `include=engagement` to fill the duration in the same call, and `include=engagement,channel` for the handle and avatar: every row is joined to the per-video lookup, which supplies likes, comments, the duration, the exact publish time and the channel; `include=channel` adds the channel's subscriber count. Each costs 1 credit per distinct video or channel filled, at most 5 per page. TITLES: the free per-video lookup swaps YouTube's English machine-translated listing title for the creator's own; a title not swapped carries `post.ext.title_maybe_translated: true` (`exact_dates=false` skips the lookup).", "tags": [ "youtube" ], "operationId": "get_youtube_search_hashtag", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 11, "x-credit-cost-formula": "1 credit for the page. include=engagement and include=channel each add 1 credit per distinct video or channel filled, at most 5 per join on a page of up to 50 rows, so a page with both is at most 11 credits; ids that could not be filled are refunded, and a repeat of the same call within the cache window costs 0. 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": "shorts" }, { "name": "continuationToken", "in": "query", "required": false, "description": "Continuation token to get more videos. Get 'continuationToken' 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": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Search for all types of content or only shorts", "schema": { "type": "string", "enum": [ "all", "shorts" ] } }, { "name": "include", "in": "query", "required": false, "description": "Set to `engagement`, `channel`, or both (`engagement,channel`) to fill more of every row in this one call. `engagement` fills `post.engagement.views`, `.likes` and `.comments`, `post.content.duration_seconds`, `post.ext.channel_id` and `post.author.display_name` where the row lacks them, and replaces a date derived from a label such as \"4 months ago\" with the exact publish time (removing `post.ext.published_precision`). `channel` puts the channel's subscriber count on `post.ext.author_followers` (YouTube's own figure, which it rounds to three significant figures above 1,000) and fills the channel's `post.author.display_name`, `.avatar_url` and `.username` where missing. It also adds the country the channel's owner set, as an ISO 3166-1 alpha-2 code on `post.ext.author_country` (null when the channel sets none). Send both to cover rows that arrive without a channel id: the video join supplies it and the channel join then uses it. Each join costs 1 credit per distinct video or channel it filled, and never more than 5 per 50; ids that could not be filled are refunded. Each join adds 0.2 to 0.7 seconds on a fresh page (one lookup per 50 ids, never more than 8 seconds). Read `data.hydration` for the rows, lookups, credits held and kept, and the time.", "schema": { "type": "string" } }, { "name": "exact_dates", "in": "query", "required": false, "description": "Exact publish dates are on by default and free. A row whose date the upstream derived from a relative label such as \"4 months ago\" (measured up to four months off) is joined to the per-video lookup for its exact publish second, at no extra credit: one lookup per page (two on a page past 50 rows, side by side), adding about 0.2 to 0.7 seconds (never more than 3). The same lookup swaps the listing title, often YouTube's English machine translation, for the creator's own, and `computed.language` follows it; a title not swapped carries `post.ext.title_maybe_translated: true`. Set to `false` to skip the lookup: rows then carry the supplier's date estimate (a day-granular or coarser label truncated to midnight UTC), marked by `post.ext.published_precision` and `post.ext.published_label`, and the listing title, marked by `post.ext.title_maybe_translated`. A row the lookup could not resolve keeps those values and markers, and `_warnings` carries `exact_dates_partial` (some rows) or `exact_dates_unavailable` (none); on `channel/videos`, whose dates are already exact, the warnings are `original_titles_partial` and `original_titles_unavailable`.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "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": "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 `continuationToken` (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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/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": "youtube", "endpoint": "/v1/youtube/search/hashtag", "data": { "items": [ { "post": { "id": "Li8RTsmujBI", "url": "https://www.youtube.com/watch?v=Li8RTsmujBI", "content": { "text": "Sample comment text (redacted).", "media_urls": null, "thumbnail_url": "https://i.ytimg.com/vi/Li8RTsmujBI/hq720.jpg?sqp=-oaymwErCNAFEJQDSFryq4qpAx0IARUAAIhCGAHYAQHiAQoIGBACGAY4AUABuAL3GA==&rs=AOn4CLAtU4QpB8L6RlwTnheFEqt3JexR6w", "duration_seconds": 219 }, "author": { "username": "user_75fd8b", "display_name": "user_9b4984", "avatar_url": "https://example.com/avatars/user_c06a0b.png", "verified": null }, "engagement": { "views": 8557, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-10-01T21:10:05.000Z", "ext": { "content_type": "video", "description": null, "channel_id": "UC6ZFN9Tx6xh-skXCuRHCDpQ", "published_label": "10 hours ago" } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": 10268 } }, { "post": { "id": "tE5qHBUDYjg", "url": "https://www.youtube.com/watch?v=tE5qHBUDYjg", "content": { "text": "Sample comment text (redacted).", "media_urls": null, "thumbnail_url": null, "duration_seconds": null }, "author": { "username": null, "display_name": "user_2a3642", "avatar_url": null, "verified": null }, "engagement": { "views": 3200, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-10-01T23:00:10.000Z", "ext": { "content_type": "short", "description": null, "channel_id": "UC2eNsx687ZQF0jQu0U8uaDA" } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": 3840 } } ], "next_cursor": "sc1.eyJjIjoiRWo0U0NTSWpjMmh2Y25Seklob3VVMEpUUTBGUmRFMWhWR2hUVmtoT2RHUlhjRU5UWWtsQ1FtZHZSVU5CVFZGQmRXOUNRa0ZuUTBWQ2F5VXpSS0FDQkJpQjRPZ1lJZ3R6WldGeVkyZ3RabVZsWkElM0QlM0QiLCJzIjpbIkxpOFJUc211akJJIiwidEU1cUhCVURZamciLCJKMjJvSWNHSWtQOCIsIk1UamhlU1ZGa3FZIiwiRVBvVElFT2xnM1EiLCJmRnlIbUh0TTJLayIsInFpWE1tLW5QNmJzIiwibkVIWVZBb2g3LUEiLCJ6d2hjRDdHbThBZyIsIkl0WGtSdE5Gam1vIiwiemxHeGQ5cEt5WmMiLCJrVTBDanVVVlFEdyIsImpQYUJwYnhobDNnIiwiVWhuMllzSkRnUUkiLCJVRTZKLVhHNkk0TSIsIjR4cXRZa3JzQmVnIiwiNWJVelpVN29zdUkiLCJpbXhvUy1DZUl3NCIsImk2V05kNkZ1QzZFIiwiek9FMFhuQTY1RkEiLCJOVTAtZ0NKR19xQSIsImhBZFRncVcxZlB3IiwiWEQybGdrU1k0MjgiLCJIZ2tObUNXbjFqNCIsInF4aXA2eUNWd3lzIiwiREUweGtnZDlPMkEiXX0", "total": null, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoic2MxLmV5SmpJam9pUldvMFUwTlRTV3BqTW1oMlkyNVNla2xvYjNWVk1FcFVVVEJHVW1SRk1XaFdSMmhVVm10b1QyUkhVbGhqUlU1VVdXdHNRMUZ0WkhaU1ZVNUNWRlpHUW1SWE9VTlJhMFp1VVRCV1EyRjVWWHBTUzBGRFFrSnBRalJQWjFsSlozUjZXbGRHZVZreVozUmFiVlpzV2tFbE0wUWxNMFFpTENKeklqcGJJa3hwT0ZKVWMyMTFha0pKSWl3aWRFVTFjVWhDVlVSWmFtY2lMQ0pLTWpKdlNXTkhTV3RRT0NJc0lrMVVhbWhsVTFaR2EzRlpJaXdpUlZCdlZFbEZUMnhuTTFFaUxDSm1SbmxJYlVoMFRUSkxheUlzSW5GcFdFMXRMVzVRTm1Keklpd2lia1ZJV1ZaQmIyZzNMVUVpTENKNmQyaGpSRGRIYlRoQlp5SXNJa2wwV0d0U2RFNUdhbTF2SWl3aWVteEhlR1E1Y0V0NVdtTWlMQ0pyVlRCRGFuVlZWbEZFZHlJc0ltcFFZVUp3WW5ob2JETm5JaXdpVldodU1sbHpTa1JuVVVraUxDSlZSVFpLTFZoSE5razBUU0lzSWpSNGNYUlphM0p6UW1Wbklpd2lOV0pWZWxwVk4yOXpkVWtpTENKcGJYaHZVeTFEWlVsM05DSXNJbWsyVjA1a05rWjFRelpGSWl3aWVrOUZNRmh1UVRZMVJrRWlMQ0pPVlRBdFowTktSMTl4UVNJc0ltaEJaRlJuY1ZjeFpsQjNJaXdpV0VReWJHZHJVMWswTWpnaUxDSklaMnRPYlVOWGJqRnFOQ0lzSW5GNGFYQTJlVU5XZDNseklpd2lSRVV3ZUd0blpEbFBNa0VpWFgwIiwiZSI6InlvdXR1YmUvc2VhcmNoL2hhc2h0YWciLCJwIjoiY29udGludWF0aW9uVG9rZW4ifQ", "has_more": true, "page_size": 26 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T07:30:03.232Z", "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" } } } } } } }, "/youtube/video/related": { "get": { "summary": "Get videos related to a YouTube video", "description": "Returns the videos YouTube lists next to a video (its \"up next\" list), usually 11 or 12, in the order YouTube shows them. Each row carries the video id, URL, title, thumbnail, duration, view count and channel name, and the channel id when YouTube gives one. The list is what YouTube shows a signed-out viewer at the moment of the call, so it changes between calls. VIEWS are YouTube's rounded figure (\"2.5B\" is 2,500,000,000); send `include=engagement` for exact counts. With `language`, YouTube writes the labels in that language (\"416 mil\") and they are read at the same rounding. DATES: the list only labels each video (\"16y ago\"), so by default every row is joined to the per-video lookup for its exact publish second and its channel, at no extra credit (one lookup per page); with `exact_dates=false` no lookup runs and `post.published_at` is null. `post.author.username` is the channel's @handle, or null for a channel that has none (`include=channel` fills it where it exists). Send `include=engagement` for likes and comments, and `include=channel` for the channel's subscriber count and avatar. TITLES: the free lookup swaps a machine-translated listing title for the creator's own; a title not swapped carries `post.ext.title_maybe_translated: true`. Accepts a watch, youtu.be or Shorts URL. A video that does not exist is a 404 and is not charged.", "tags": [ "youtube" ], "operationId": "get_youtube_video_related", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 11, "x-credit-cost-formula": "1 credit for the page. include=engagement and include=channel each add 1 credit per distinct video or channel filled, at most 5 per join on a page of up to 50 rows, so a page with both is at most 11 credits; ids that could not be filled are refunded, and a repeat of the same call within the cache window costs 0.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full URL of the YouTube video or Short", "schema": { "type": "string" }, "example": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }, { "name": "language", "in": "query", "required": false, "description": "Preferred language for the listing (mapped to Accept-Language; not guaranteed due to YouTube localization behavior). 2 letter language code, ie 'en', 'es', 'fr' etc.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Set to `engagement`, `channel`, or both (`engagement,channel`) to fill more of every row in this one call. `engagement` fills `post.engagement.views`, `.likes` and `.comments`, `post.content.duration_seconds`, `post.ext.channel_id` and `post.author.display_name` where the row lacks them, and replaces a date derived from a label such as \"4 months ago\" with the exact publish time (removing `post.ext.published_precision`). `channel` puts the channel's subscriber count on `post.ext.author_followers` (YouTube's own figure, which it rounds to three significant figures above 1,000) and fills the channel's `post.author.display_name`, `.avatar_url` and `.username` where missing. It also adds the country the channel's owner set, as an ISO 3166-1 alpha-2 code on `post.ext.author_country` (null when the channel sets none). Send both to cover rows that arrive without a channel id: the video join supplies it and the channel join then uses it. Each join costs 1 credit per distinct video or channel it filled, and never more than 5 per 50; ids that could not be filled are refunded. Each join adds 0.2 to 0.7 seconds on a fresh page (one lookup per 50 ids, never more than 8 seconds). Read `data.hydration` for the rows, lookups, credits held and kept, and the time.", "schema": { "type": "string" } }, { "name": "exact_dates", "in": "query", "required": false, "description": "Exact publish dates are on by default and free. A row whose date the upstream derived from a relative label such as \"4 months ago\" (measured up to four months off) is joined to the per-video lookup for its exact publish second, at no extra credit: one lookup per page (two on a page past 50 rows, side by side), adding about 0.2 to 0.7 seconds (never more than 3). The same lookup swaps the listing title, often YouTube's English machine translation, for the creator's own, and `computed.language` follows it; a title not swapped carries `post.ext.title_maybe_translated: true`. Set to `false` to skip the lookup: rows then carry the supplier's date estimate (a day-granular or coarser label truncated to midnight UTC), marked by `post.ext.published_precision` and `post.ext.published_label`, and the listing title, marked by `post.ext.title_maybe_translated`. A row the lookup could not resolve keeps those values and markers, and `_warnings` carries `exact_dates_partial` (some rows) or `exact_dates_unavailable` (none); on `channel/videos`, whose dates are already exact, the warnings are `original_titles_partial` and `original_titles_unavailable`.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/video/related" }, "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" } } } } } } }, "/youtube/shorts/trending": { "get": { "summary": "Get trending YouTube shorts", "description": "Returns currently trending YouTube Shorts with view counts, like counts, channel info, and thumbnails. Send `include=channel` to add each Short's channel subscriber count (`post.ext.author_followers`) in the same call.", "tags": [ "youtube" ], "operationId": "get_youtube_shorts_trending", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "x-credit-cost-min": 5, "x-credit-cost-max": 15, "x-credit-cost-formula": "5 credits for the feed. include=channel adds 1 credit per distinct channel filled, at most 5 per 50 channels (the feed carries about 70, so at most 10); channels that could not be read are refunded, and a repeat of the same call within the cache window costs 0.", "parameters": [ { "name": "include", "in": "query", "required": false, "description": "Set to `channel` (one token only) to add each row's channel stats in this one call. `channel` puts the channel's subscriber count on `post.ext.author_followers` (YouTube's own figure, which it rounds to three significant figures above 1,000) and fills the channel's `post.author.display_name`, `.avatar_url` and `.username` where missing. It also adds the country the channel's owner set, as an ISO 3166-1 alpha-2 code on `post.ext.author_country` (null when the channel sets none). Each join costs 1 credit per distinct video or channel it filled, and never more than 5 per 50; ids that could not be filled are refunded. Each join adds 0.2 to 0.7 seconds on a fresh page (one lookup per 50 ids, never more than 8 seconds). Read `data.hydration` for the rows, lookups, credits held and kept, and the time.", "schema": { "type": "string", "enum": [ "channel" ] } }, { "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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/shorts/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/profile/videos", "data": { "items": [ { "post": { "id": "7658005300657638669", "url": "https://www.tiktok.com/@charlidamelio/video/7658005300657638669", "content": { "text": "dc @lara.joanna ", "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": "charlidamelio", "display_name": "charli d’amelio", "avatar_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D", "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/@charlidamelio/video/7657606229484670221", "content": { "text": "@Alexa Davis ", "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": "charlidamelio", "display_name": "charli d’amelio", "avatar_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D", "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/@charlidamelio/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": "charlidamelio", "display_name": "charli d’amelio", "avatar_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D", "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" } } } } } } }, "/youtube/video/transcript": { "get": { "summary": "Get YouTube video transcript", "description": "Returns the transcript of a YouTube video as timestamped segments: each with text, start `offset` and `duration` (seconds), language, word count, and speech rate. Supports multiple languages via `language`. Without `language`, the transcript is in the language spoken in the video's original audio when YouTube publishes it, not a dubbed track, even when the video has auto-dubbed audio in other languages; each segment's `lang` says which language you got. When no transcript exists (the owner disabled captions, the video is members-only, login-gated or gone, or no caption track matches the requested language) the endpoint returns 404 RESOURCE_NOT_FOUND with `error.details.reason` set to `captions_disabled`, `members_only`, `login_required`, `no_captions`, or `video_gone`, and no credits are charged. Retrying returns the same result, with one exception: a video uploaded in the last day can answer `captions_disabled` until YouTube generates its automatic captions, so a retry a few hours later can succeed.", "tags": [ "youtube" ], "operationId": "get_youtube_video_transcript", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 3, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full URL of the YouTube video", "schema": { "type": "string" }, "example": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }, { "name": "language", "in": "query", "required": false, "description": "2 letter language code, ie 'en', 'es', 'fr' etc. If no caption track matches the language you specify, the request returns 404 RESOURCE_NOT_FOUND (reason `no_captions`) at 0 credits. Omit it to get the video's original spoken language.", "schema": { "type": "string" } }, { "name": "moments", "in": "query", "required": false, "description": "Optional CSV of moment kinds to find in the timestamped transcript: brand, sponsor_read, product_demo, call_to_action. Returns data.moments = [{ kind, start_ms, end_ms, quote }]. Quote is copied from the transcript. Times come from the segments, never from the judge. 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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/video/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": "youtube", "endpoint": "/v1/youtube/video/transcript", "data": { "transcript": [ { "text": "[♪♪♪]", "duration": 1.68, "offset": 1.36, "lang": "en", "wordCount": 0, "speechRate": 0 }, { "text": "♪ We're no strangers to love ♪", "duration": 3.24, "offset": 18.64, "lang": "en", "wordCount": 5, "speechRate": 93 } ] }, "credits_used": 0, "request_id": "req_example000000", "cached": true, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T12:45:01.380Z", "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" } } } } } } }, "/youtube/channel/playlists": { "get": { "summary": "List a YouTube channel's playlists", "description": "Fetches playlists from a YouTube channel's Playlists tab (playlist ID, title, thumbnail, video count, channel info, and playlist URL) plus a `continuationToken` when more results are available. Pass `handle` or `channelId` for the first page; forward `continuationToken` for subsequent pages.", "tags": [ "youtube" ], "operationId": "get_youtube_channel_playlists", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-socialcrawl-oneOf": [ [ "channelId", "handle" ] ], "parameters": [ { "name": "channelId", "in": "query", "required": false, "description": "YouTube channel ID. (one of: channelId, handle; at least one required)", "schema": { "type": "string" } }, { "name": "handle", "in": "query", "required": false, "description": "YouTube channel handle (with or without @). (one of: channelId, handle; at least one required)", "schema": { "type": "string" }, "example": "MrBeast" }, { "name": "continuationToken", "in": "query", "required": false, "description": "Continuation token from a previous response: fetches the next page. 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 `continuationToken` (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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/channel/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/videos", "data": { "items": [ { "post": { "id": "7658005300657638669", "url": "https://www.tiktok.com/@charlidamelio/video/7658005300657638669", "content": { "text": "dc @lara.joanna ", "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": "charlidamelio", "display_name": "charli d’amelio", "avatar_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D", "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/@charlidamelio/video/7657606229484670221", "content": { "text": "@Alexa Davis ", "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": "charlidamelio", "display_name": "charli d’amelio", "avatar_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D", "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/@charlidamelio/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": "charlidamelio", "display_name": "charli d’amelio", "avatar_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D", "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" } } } } } } }, "/youtube/channel/lives": { "get": { "summary": "List a YouTube channel's live streams", "description": "Fetches live streams and past streams from a YouTube channel's Live tab (title, URL, thumbnail, view count, publish time, duration) plus a `continuationToken` when more results are available. Pass `handle` or `channelId` for the first page; forward `continuationToken` for subsequent pages. DATES: this tab publishes no exact timestamp, only a relative label (\"Streamed 3 weeks ago\"), so by default every row is joined to the per-video lookup for its exact publish second, at no extra credit (one lookup per page). Send `exact_dates=false` to keep the label-derived estimate instead, marked by `post.ext.published_precision`. The tab also publishes no like or comment counts. Send `include=engagement` and every row is joined, in the same call, to the per-video lookup: likes, comments, the exact publish time and the channel id land on each row (1 credit per distinct stream filled, at most 5 per page); `include=channel` adds the channel's subscriber count (1 credit). TITLES: the free per-video lookup swaps YouTube's English machine-translated listing title for the creator's own; a title not swapped carries `post.ext.title_maybe_translated: true` (`exact_dates=false` skips the lookup).", "tags": [ "youtube" ], "operationId": "get_youtube_channel_lives", "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 for the page. include=engagement adds 1 credit per distinct stream filled, at most 5 per page; include=channel adds 1 credit for the single channel lookup the page shares. Anything that could not be filled is refunded, so a page with both is at most 7 credits, and a repeat of the same call within the cache window costs 0. 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": [ [ "channelId", "handle" ] ], "parameters": [ { "name": "channelId", "in": "query", "required": false, "description": "YouTube channel ID. (one of: channelId, handle; at least one required)", "schema": { "type": "string" } }, { "name": "handle", "in": "query", "required": false, "description": "YouTube channel handle (with or without @). (one of: channelId, handle; at least one required)", "schema": { "type": "string" }, "example": "IShowSpeed" }, { "name": "continuationToken", "in": "query", "required": false, "description": "Continuation token from a previous response: fetches the next page. Native upstream cursor param. Send the universal `cursor` instead: the API maps it to this name for you.", "deprecated": true, "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Set to `engagement`, `channel`, or both (`engagement,channel`) to fill more of every row in this one call. `engagement` fills `post.engagement.views`, `.likes` and `.comments`, `post.content.duration_seconds`, `post.ext.channel_id` and `post.author.display_name` where the row lacks them, and replaces a date derived from a label such as \"4 months ago\" with the exact publish time (removing `post.ext.published_precision`). The engagement join costs 1 credit per distinct stream it filled, never more than 5 per page, and streams that could not be filled are refunded. `channel` adds the channel's subscriber count (`post.ext.author_followers`, YouTube's own figure, rounded to three significant figures above 1,000) plus its avatar: every row is the same channel, so it is one lookup, 1 credit, refunded if it could not be read. Each join adds 0.2 to 0.7 seconds on a fresh page (one lookup per 50 ids, never more than 8 seconds). Read `data.hydration` for the rows, lookups, credits held and kept, and the time.", "schema": { "type": "string" } }, { "name": "exact_dates", "in": "query", "required": false, "description": "Exact publish dates are on by default and free. A row whose date the upstream derived from a relative label such as \"4 months ago\" (measured up to four months off) is joined to the per-video lookup for its exact publish second, at no extra credit: one lookup per page (two on a page past 50 rows, side by side), adding about 0.2 to 0.7 seconds (never more than 3). The same lookup swaps the listing title, often YouTube's English machine translation, for the creator's own, and `computed.language` follows it; a title not swapped carries `post.ext.title_maybe_translated: true`. Set to `false` to skip the lookup: rows then carry the supplier's date estimate (a day-granular or coarser label truncated to midnight UTC), marked by `post.ext.published_precision` and `post.ext.published_label`, and the listing title, marked by `post.ext.title_maybe_translated`. A row the lookup could not resolve keeps those values and markers, and `_warnings` carries `exact_dates_partial` (some rows) or `exact_dates_unavailable` (none); on `channel/videos`, whose dates are already exact, the warnings are `original_titles_partial` and `original_titles_unavailable`.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "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 `continuationToken` (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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/channel/lives" }, "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": "youtube", "endpoint": "/v1/youtube/channel/lives", "data": { "items": [ { "post": { "id": "o1_FvfJD8fg", "url": "https://www.youtube.com/watch?v=o1_FvfJD8fg", "content": { "text": "I GOT A JOB AT KFC!", "media_urls": null, "thumbnail_url": "https://i.ytimg.com/vi/o1_FvfJD8fg/hq720.jpg?sqp=-oaymwEnCNAFEJQDSFryq4qpAxkIARUAAIhCGAHYAQHiAQoIGBACGAY4AUABovOX_wMOCPje5dUGGODqBCDgqAE=&rs=AOn4CLC9xeVhNw4Ai-w9Lj56gaWSyBqeHw&usqp=CBU", "duration_seconds": 11033 }, "author": { "username": "user_6a16c3", "display_name": null, "avatar_url": null, "verified": null }, "engagement": { "views": 5100000, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-27T18:48:39.000Z", "ext": { "content_type": "live", "channel_id": null } }, "computed": { "engagement_rate": null, "language": null, "content_category": "other", "estimated_reach": 6120000 } }, { "post": { "id": "GfCnZ8cAYvQ", "url": "https://www.youtube.com/watch?v=GfCnZ8cAYvQ", "content": { "text": "JOIN THIS STREAM, WIN AN IPHONE 18!", "media_urls": null, "thumbnail_url": "https://i.ytimg.com/vi/GfCnZ8cAYvQ/hq720.jpg?sqp=-oaymwEnCNAFEJQDSFryq4qpAxkIARUAAIhCGAHYAQHiAQoIGBACGAY4AUABovOX_wMOCMzextUGGODqBCDgqAE=&rs=AOn4CLBr6IKi8id-0s0QTgK6COVFT96D8g&usqp=CBU", "duration_seconds": 13826 }, "author": { "username": "user_6a16c3", "display_name": null, "avatar_url": null, "verified": null }, "engagement": { "views": 5300000, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-21T22:04:12.000Z", "ext": { "content_type": "live", "channel_id": null } }, "computed": { "engagement_rate": null, "language": null, "content_category": "other", "estimated_reach": 6360000 } } ], "next_cursor": "4qmFsgKdCxIYVUNXc0RGY0loWTJEQmkzR0I1dXlrR1hBGoALOGdhY0NCcVpDSEtXQ0RxVENBb2tObUl4TURBd1lXSXRNREF3TUMweU1UTmpMVGd4TmprdFpEUm1OVFEzWldabE56RTRFdWdIUVdaelYydHNObEJRTm5VMmEyTjBOMHRHZDFoVGVqRnpTMlprYTNOdU9WVmpVVFZWVkRkQ1dqSTFTSEJZZHpoWFRFZ3lVbEpzVVU1V1FXWjBlVlJyUTA1TlREQmhlR0ZsTjJwalpqaFNORTFYWTIxWGJtdHpURUU0U1d0WGRqVm5SbUpRYW5CR1NtY3RPRkp1WDAxdVZFcG1ZME5DYUhodVFqbHFNSGxOYzJWbVNsSnpVMTlJV210eGRXMWpRa1J0UlRkVWVTMVFOMFZPVVRaYWIxRnVaV2RQTjNkaWIzcDRibUpyVkRCamJXTlhjRWhPVlZkdFIwaDRZbk50U1U4MlUxaGxORGg1V1hKZk4zRkpiRnAxU3pCaWFIUkxWREpyYzJvek9VNHdMVEIzYWtKaVJIcEtMV2hrWWpkSk5uTlhkWFJMY0RRMVJtUlNkR0ZuU2poeldtNDRkV3Q2ZW1vMU5EVkpMV296U1VKNFNGSXpPREZSY0dnd05tNXpXVkpXVjBoVExURjNUbWhYTlZKNVJYWjBRWEJxVEVGVlQzbDRiRUpvTXpabmJYYzNiR0V5Vmt4MlNIRXpSRGRSTTJWNWRXY3lWblJKVjFsNlIyVnBkek5ZUmt0a1UwbG5XV2RIUjAxb1MyZzJiVEZFTjJsTFNrczJYMUZQUkRFeVNqUmhjbGxoVkhZMlF6VTNhSHAxYnpGclpXaE1RVXgzU2pBMVNuTlpORGw0VVdkTWRsaHBkVVJDUzNKVmJFMDBOeTFuZHpkVVVVWjFlRk5VV1hGSVVqbHlORlZzTkVSeGIzVkhYM001Umxad1ZVaHdXR0pQY1VWWU9ITXRNeTFLVlUwME5UbE5OSGM0TjFSTWJYWlJSM0UzU0VSMGVVczFlbk5wT0RNelVUZzVUVWt4Ym5oa2NrWnZVMlZFVVdoSU1ETXliVFJWVEZocVVuVm5OVUpTVDNKSldtUm5TRTF0WmxWRE1rSm9ZbmN3U2tsWVRrRkliR3QxWTFCV2EwUjBWMUl3U2pCbVlYVlJkMko0YkUxNlZHTnNaa28yUm1ScFZGTmxWRGxMYzNreGNrZG1VVzluVGxSRlJVTmFWRUZrUW5kYWJrd3RhV3MyWkhWeWRtOUhZVlJrVGxOU2VXdzRaMUEzY0haVmQxOUdOWEppYlROVFNWaEJhREl0YlVnd1pGTlpVRjlMUm14bGVVTm9jSFJCZFZRM1FrZFRZMG8zWXpReWIxUlZWM2g0UTIxMmR6ZENSbGRoYXkxek1HTTVZM2xIVWpORmJsVkhUV1pmVTJwVWNtVTJhMFI2Y0cxTVRrSkJYMkp6Y1ZkRmVWWkZia280UzBOVVdqSm5WazlKV0U5bVZWSjVlR0pxVlhwWmFuSk1iVEpZYjBoMGJrTXhUemhRTTBkQmJFY3hZbEJhY2tGalVrZFNSVmxOUlhwdmRreEpWbkZPYjBvd1kwNW1TRk50WmxGTWFqY3phbHA2TUdwQ2FXZzFielYyYTBGTExVOUpWbk5RVTI5WVVUWkVWVzVIVEhoSGRYaFlNVEJwTFV4WlNHdFdNa2RYTXpSZk5saGZZVk0xVDFvNVIwbFBhemhqVVZaelJHNW9WVkJ1U2t0d1IxOVdValZHYkZWS1QzUlFiMDlLYm1WWU16TjFlVEphZWpZeVYxaEtOMGhrTWw4NGNrUnplVGN3UmxGbmRtTnZTM3BKTW1WU1VpMHhjMk5sYmxWSmVrSnZkbE5GZG14SGRWWmFOekJGYzFWelQwSm1WbmQxUlJnTQ%3D%3D", "total": null, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiNHFtRnNnS2RDeElZVlVOWGMwUkdZMGxvV1RKRVFta3pSMEkxZFhsclIxaEJHb0FMT0dkaFkwTkNjVnBEU0V0WFEwUnhWRU5CYjJ0T2JVbDRUVVJCZDFsWFNYUk5SRUYzVFVNd2VVMVVUbXBNVkdkNFRtcHJkRnBFVW0xT1ZGRXpXbGRhYkU1NlJUUkZkV2RJVVZkYWVsWXlkSE5PYkVKUlRtNVZNbUV5VGpCT01IUkhaREZvVkdWcVJucFRNbHByWVROT2RVOVdWbXBWVkZaV1ZrUmtRMWRxU1RGVFNFSlpaSHBvV0ZSRlozbFZiRXB6VlZVMVYxRlhXakJsVmxKeVVUQTFUbFJFUW1obFIwWnNUakp3YWxwcWFGTk9SVEZZV1RJeFdHSnRkSHBVUlVVMFUxZDBXR1JxVm01U2JVcFJZVzVDUjFOdFkzUlBSa3AxV0RBeGRWWkZjRzFaTUU1RFlVaG9kVkZxYkhGTlNHeE9ZekpXYlZOc1NucFZNVGxKVjIxMGVHUlhNV3BSYTFKMFVsUmtWV1ZUTVZGT01GWlBWVlJhWVdJeFJuVmFWMlJRVGpOa2FXSXpjRFJpYlVweVZrUkNhbUpYVGxoalJXaFBWbFprZEZJd2FEUlpiazUwVTFVNE1sVXhhR3hPUkdnMVYxaEtaazR6UmtwaVJuQXhVM3BDYVdGSVVreFdSRXB5WXpKdmVrOVZOSGRNVkVJellXdEthVkpJY0V0TVYyaHJXV3BrU2s1dVRsaGtXRkpNWTBSUk1WSnRVbE5rUjBadVUycG9lbGR0TkRSa1YzUTJaVzF2TVU1RVZrcE1WMjk2VTFWS05GTkdTWHBQUkVaU1kwZG5kMDV0TlhwWFZrcFhWakJvVkV4VVJqTlViV2hZVGxaS05WSllXakJSV0VKeFZFVkdWbFF6YkRSaVJVcHZUWHBhYm1KWVl6TmlSMFY1Vm10NE1sTklSWHBTUkdSU1RUSldOV1JYWTNsV2JsSktWakZzTmxJeVZuQmtlazVaVW10MGExVXdiRzVYVjJSSVVqQXhiMU15WnpKaVZFWkZUakpzVEZOcmN6SllNVVpRVWtSRmVWTnFVbWhqYkd4b1ZraFpNbEY2VlROaFNIQXhZbnBHY2xwWGFFMVJWWGd6VTJwQk1WTnVUbHBPUkd3MFZWZGtUV1JzYUhCa1ZWSkRVek5LVm1KRk1EQk9lVEZ1Wkhwa1ZWVlZXakZsUms1VlYxaEdTVlZxYkhsT1JsWnpUa1ZTZUdJelZraFlNMDAxVW14YWQxWlZhSGRYUjBwUVkxVldXVTlJVFhSTmVURkxWbFV3TUU1VWJFNU9TR00wVGpGU1RXSllXbEpTTTBVelUwVlNNR1ZWY3pGbGJrNXdUMFJOZWxWVVp6VlVWV3Q0WW01b2EyTnJXblpWTWxaRlZWZG9TVTFFVFhsaVZGSldWRVpvY1ZWdVZtNU9WVXBUVkROS1NsZHRVbTVUUlRGMFdteFdSRTFyU205WmJtTjNVMnRzV1ZSclJrbGlSM1F4V1RGQ1YyRXdVakJXTVVsM1UycENiVmxZVmxKa01rbzBZa1V4TmxaSFRuTmFhMjh5VW0xU2NGWkdUbXhXUkd4TVl6TnJlR05yWkcxVlZ6bHVWR3hTUmxKVlRtRldSVVpyVVc1a1lXSnJkM1JoVjNNeVdraFdlV1J0T1VoWlZsSnJWR3hPVTJWWGR6UmFNVUV6WTBoYVZtUXhPVWRPV0VwcFlsUk9WRk5XYUVKaFJFbDBZbFZuZDFwR1RscFZSamxNVW0xNGJHVlZUbTlqU0ZKQ1pGWlJNMUZyWkZSWk1HOHpXWHBSZVdJeFVsWldNMmcwVVRJeE1tUjZaRU5TYkdSb1lYa3hlazFIVFRWWk0yeElWV3BPUm1Kc1ZraFVWMXBtVlRKd1ZXTnRWVEpoTUZJMlkwY3hUVlJyU2tKWU1rcDZZMVprUm1WV1drWmlhMjgwVXpCT1ZWZHFTbTVXYXpsS1YwVTViVlpXU2pWbFIwcHhWbGh3V21GdVNrMWlWRXBaWWpCb01HSnJUWGhVZW1oUlRUQmtRbUpGWTNoWmJFSmhZMnRHYWxWclpGTlNWbXhPVWxod2RtUnJlRXBXYmtaUFlqQnZkMWt3TlcxVFJrNTBXbXhHVFdGcVkzcGhiSEEyVFVkd1EyRlhaekZpZWxZeVlUQkdURXhWT1VwV2JrNVJWVEk1V1ZWVVdrVldWelZJVkVob1NHUllhRmxOVkVKd1RGVjRXbE5IZEZkTmEyUllUWHBTWms1c2FHWlpWazB4VkRGdk5WSXdiRkJoZW1ocVZWWmFlbEpITlc5V1ZrSjFVMnQwZDFJeE9WZFZhbFpIWWtaV1MxUXpVbEZpTURsTFltMVdXVTE2VGpGbFZFcGhaV3BaZVZZeGFFdE9NR2hyVFd3NE5HTnJVbnBsVkdOM1VteEdibVJ0VG5aVE0zQktUVzFXVTFWcE1IaGpNazVzWW14V1NtVnJTblprYkU1R1pHMTRTR1JXV21GT2VrSkdZekZXZWxRd1NtMVdibVF4VWxKblRRJTNEJTNEIiwiZSI6InlvdXR1YmUvY2hhbm5lbC9saXZlcyIsInAiOiJjb250aW51YXRpb25Ub2tlbiJ9", "has_more": true, "page_size": 30 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T07:30:06.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" } } } } } } }, "/youtube/channel/community-posts": { "get": { "summary": "List a YouTube channel's community posts", "description": "Fetches community posts from a YouTube channel's Posts tab (post ID, URL, content, images, attached video, like count, publish time, channel info) plus a `continuationToken` when more results are available. Pass `handle` or `channelId` for the first page; forward `continuationToken` for subsequent pages. DATES ARE APPROXIMATE: `post.published_at` is derived from the tab's own relative label (\"2 days ago\"), so its time-of-day is not real and the date is only as precise as that label. This tab publishes no exact timestamp.", "tags": [ "youtube" ], "operationId": "get_youtube_channel_community_posts", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-socialcrawl-oneOf": [ [ "channelId", "handle" ] ], "parameters": [ { "name": "channelId", "in": "query", "required": false, "description": "YouTube channel ID. (one of: channelId, handle; at least one required)", "schema": { "type": "string" } }, { "name": "handle", "in": "query", "required": false, "description": "YouTube channel handle (with or without @). (one of: channelId, handle; at least one required)", "schema": { "type": "string" }, "example": "MrBeast" }, { "name": "continuationToken", "in": "query", "required": false, "description": "Continuation token from a previous response: fetches the next page. 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 `continuationToken` (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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/channel/community-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": "youtube", "endpoint": "/v1/youtube/channel/community-posts", "data": { "items": [ { "post": { "id": "UgkxHIfkQ3K2my65-kPq4VkRv9KrBRyN7alx", "url": "https://www.youtube.com/post/UgkxHIfkQ3K2my65-kPq4VkRv9KrBRyN7alx", "content": { "text": "NO MORE WAITING, this Saturday “Eat Everything In A Grocery Store Win $1,000,000” finally goes live! You’ll get to see if Juan and the gang pulled it off :D", "media_urls": [ "https://yt3.ggpht.com/-gQueci3cQXl50-Tgiv_Ru65aUfw2-6aHe9ny2Iy1KWoU1iAALkCZ9VeiZkH5tcqqiAjaTjb50D7iQ=s1320-c-fcrop64=1,35f50000ca0affff-rw-nd-v1" ], "thumbnail_url": "https://yt3.ggpht.com/-gQueci3cQXl50-Tgiv_Ru65aUfw2-6aHe9ny2Iy1KWoU1iAALkCZ9VeiZkH5tcqqiAjaTjb50D7iQ=s1320-c-fcrop64=1,35f50000ca0affff-rw-nd-v1", "duration_seconds": null }, "author": { "username": "user_e32d6a", "display_name": "MrBeast", "avatar_url": null, "verified": null }, "engagement": { "views": null, "likes": 212000, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-29T00:00:00.000Z", "ext": { "channel_id": "UCX6OQ3DkcsbYNE6H8uQQuVA", "published_label": "3 days ago", "published_precision": "day" } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": null } }, { "post": { "id": "UgkxzJ6r7VLAK03TN5Gjq7YpjHmjtee_Rdn9", "url": "https://www.youtube.com/post/UgkxzJ6r7VLAK03TN5Gjq7YpjHmjtee_Rdn9", "content": { "text": "The Most Dangerous Games, my new book with James Patterson, launches tomorrow! To celebrate, I'm giving away $1,000,000 to one person who enters our skill-based contest at https://www.themostdangerousgames.com. It starts Sept.1, your ticket to play is the book! Find it tomorrow wherever you buy books :)", "media_urls": [ "https://yt3.ggpht.com/rhesNywNa9lXn-aQdFLZnqffZ30LdDsgLJGOEFt6n8RWKAX3_La47jPwgIAW5OXgNiBJmuSHYe5G_Y8=s5464-c-fcrop64=1,00000000ffffffff-rw-nd-v1", "https://yt3.ggpht.com/22Wmjp39NDMg2OycAU3icJUUD0lUVI334ZqMpexccPKXraVr57pNZNglJ83x3HB-AW2QkoPrkny12w=s1000-c-fcrop64=1,00000000ffffffff-rw-nd-v1" ], "thumbnail_url": "https://yt3.ggpht.com/rhesNywNa9lXn-aQdFLZnqffZ30LdDsgLJGOEFt6n8RWKAX3_La47jPwgIAW5OXgNiBJmuSHYe5G_Y8=s5464-c-fcrop64=1,00000000ffffffff-rw-nd-v1", "duration_seconds": null }, "author": { "username": "user_e32d6a", "display_name": "MrBeast", "avatar_url": null, "verified": null }, "engagement": { "views": null, "likes": 413000, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-02T00:00:00.000Z", "ext": { "channel_id": "UCX6OQ3DkcsbYNE6H8uQQuVA", "published_label": "1 month ago", "published_precision": "month" } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": null } } ], "next_cursor": "4qmFsgKTARIYVUNYNk9RM0RrY3NiWU5FNkg4dVFRdVZBGl5FZ1Z3YjNOMGM3Z0JBSklEQUtvREtBb2tVVEpvUTFKR1VsaFhha1pyVmtkNFIxVnFRbGRVVjBaV1ZGaFNUMUpWV2tSU1ZVWkNLQXJ5QmdrS0Iwb0FvZ0VDQ0FFJTNEmgIWYmFja3N0YWdlLWl0ZW0tc2VjdGlvbg%3D%3D", "total": null, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiNHFtRnNnS1RBUklZVlVOWU5rOVJNMFJyWTNOaVdVNUZOa2c0ZFZGUmRWWkJHbDVGWjFaM1lqTk9NR00zWjBKQlNrbEVRVXR2UkV0QmIydFZWRXB2VVRGS1IxVnNhRmhoYTFweVZtdGtORkl4Vm5GUmJHUlZWakJhVjFaR2FGTlVNVXBXVjJ0U1UxWlZXa05MUVhKNVFtZHJTMEl3YjBGdlowVkRRMEZGSlRORW1nSVdZbUZqYTNOMFlXZGxMV2wwWlcwdGMyVmpkR2x2YmclM0QlM0QiLCJlIjoieW91dHViZS9jaGFubmVsL2NvbW11bml0eS1wb3N0cyIsInAiOiJjb250aW51YXRpb25Ub2tlbiJ9", "has_more": true, "page_size": 10 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T07:30:12.969Z", "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" } } } } } } }, "/youtube/videos/trending": { "get": { "summary": "Get trending YouTube videos", "description": "Returns the most popular (trending) YouTube videos for a region and category (title, thumbnail, duration, view/like/comment counts, channel, and publish time) plus a `cursor` when more results are available. Filter by `region` (ISO country) and `category` (YouTube category id); forward `cursor` for subsequent pages. Send `include=channel` to add each video's channel subscriber count (`post.ext.author_followers`) in the same call.", "tags": [ "youtube" ], "operationId": "get_youtube_videos_trending", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 6, "x-credit-cost-formula": "1 credit for the page. include=channel adds 1 credit per distinct channel filled, at most 5 per 50 channels; channels that could not be read are refunded, and a repeat of the same call within the cache window costs 0. 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": "region", "in": "query", "required": false, "description": "ISO 3166-1 alpha-2 country code (e.g. US, GB, KR).", "schema": { "type": "string" }, "example": "US" }, { "name": "category", "in": "query", "required": false, "description": "YouTube video category id (e.g. 10 = Music, 20 = Gaming), or a name: music, gaming, sports, news. The chart weights the category rather than filtering strictly, so check `post.ext.categoryTitle` on each row. Any other word is a free 400.", "schema": { "type": "string" }, "example": "10" }, { "name": "language", "in": "query", "required": false, "description": "Localization language (ISO 639-1) for titles/metadata.", "schema": { "type": "string" } }, { "name": "max_results", "in": "query", "required": false, "description": "Maximum number of videos to return (1-50).", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous response: fetches the next page.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Set to `channel` (one token only) to add each row's channel stats in this one call. `channel` puts the channel's subscriber count on `post.ext.author_followers` (YouTube's own figure, which it rounds to three significant figures above 1,000) and fills the channel's `post.author.display_name`, `.avatar_url` and `.username` where missing. It also adds the country the channel's owner set, as an ISO 3166-1 alpha-2 code on `post.ext.author_country` (null when the channel sets none). Each join costs 1 credit per distinct video or channel it filled, and never more than 5 per 50; ids that could not be filled are refunded. Each join adds 0.2 to 0.7 seconds on a fresh page (one lookup per 50 ids, never more than 8 seconds). Read `data.hydration` for the rows, lookups, credits held and kept, and the time.", "schema": { "type": "string", "enum": [ "channel" ] } }, { "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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/videos/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": "youtube", "endpoint": "/v1/youtube/videos/trending", "data": { "items": [ { "post": { "id": "V-uIp-WuD60", "url": "https://www.youtube.com/watch?v=V-uIp-WuD60", "content": { "text": "Sample comment text (redacted).", "media_urls": null, "thumbnail_url": "https://i.ytimg.com/vi/V-uIp-WuD60/hqdefault.jpg", "duration_seconds": 226 }, "author": { "username": null, "display_name": "user_a9a776", "avatar_url": null, "verified": null }, "engagement": { "views": 6282558, "likes": 90901, "comments": 4922, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-25T04:02:10.000Z", "ext": { "tags": [ "Taylor Swift", "テイラースウィフト" ], "categoryId": "10", "categoryTitle": "Music", "topicCategories": [ "https://en.wikipedia.org/wiki/Music", "https://en.wikipedia.org/wiki/Pop_music" ], "duration": "PT3M46S", "license": "youtube", "madeForKids": false, "defaultAudioLanguage": "en", "hasPaidProductPlacement": false, "caption": "Sample comment text (redacted).", "description": "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).", "default_language": "en", "channel_id": "UCPC0L1d253x-KuMNwa05TpA" } }, "computed": { "engagement_rate": 0.015252, "language": null, "content_category": "other", "estimated_reach": 7539070 } }, { "post": { "id": "jfVVXYTZykw", "url": "https://www.youtube.com/watch?v=jfVVXYTZykw", "content": { "text": "Sample comment text (redacted).", "media_urls": null, "thumbnail_url": "https://i.ytimg.com/vi/jfVVXYTZykw/hqdefault.jpg", "duration_seconds": 210 }, "author": { "username": null, "display_name": "user_c2ce09", "avatar_url": null, "verified": null }, "engagement": { "views": 4285243, "likes": 110685, "comments": 7128, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-26T00:01:38.000Z", "ext": { "categoryId": "10", "categoryTitle": "Music", "topicCategories": [ "https://en.wikipedia.org/wiki/Independent_music", "https://en.wikipedia.org/wiki/Music" ], "duration": "PT3M30S", "license": "youtube", "madeForKids": false, "defaultAudioLanguage": "en-US", "hasPaidProductPlacement": false, "caption": "Sample comment text (redacted).", "description": "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).", "default_language": "en", "channel_id": "UCqECaJ8Gagnn7YCbPEzWH6g" } }, "computed": { "engagement_rate": 0.027493, "language": null, "content_category": "other", "estimated_reach": 5142292 } } ], "next_cursor": "CAIQAA", "total": 30, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiQ0FJUUFBIiwiZSI6InlvdXR1YmUvdmlkZW9zL3RyZW5kaW5nIiwicCI6ImN1cnNvciJ9", "has_more": true, "page_size": 2 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T07:30:14.999Z", "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" } } } } } } }, "/youtube/playlist/items": { "get": { "summary": "List the videos in a YouTube playlist", "description": "Returns the videos in a YouTube playlist in playlist order (video id, title, thumbnail, the video's own channel as `post.author.display_name` and `post.ext.channel_id`, the video's publish date, and its position and playlist-insertion time on `post.ext`) plus a `cursor` when more results are available. Pass `playlist_id` for the first page; forward `cursor` for subsequent pages. YouTube's playlist listing carries no view, like or comment counts and no duration, so on a plain call those are null. Send `include=engagement` and every row is joined, in the same call, to the per-video lookup that carries them, and `include=channel` adds each video's channel subscriber count; each costs 1 credit per distinct video or channel filled, at most 5 per page. `/v1/youtube/playlist` returns the same rows and additionally has a second source behind it.", "tags": [ "youtube" ], "operationId": "get_youtube_playlist_items", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 11, "x-credit-cost-formula": "1 credit for the page. include=engagement and include=channel each add 1 credit per distinct video or channel filled, at most 5 per join on a page of up to 50 rows, so a page with both is at most 11 credits; ids that could not be filled are refunded, and a repeat of the same call within the cache window costs 0. 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": "playlist_id", "in": "query", "required": true, "description": "YouTube playlist id (the value after `list=` in a playlist URL).", "schema": { "type": "string" }, "example": "PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI" }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous response: fetches the next page.", "schema": { "type": "string" } }, { "name": "channel_id", "in": "query", "required": false, "description": "YouTube channel id: pages that channel's uploads instead of a playlist.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Set to `engagement`, `channel`, or both (`engagement,channel`) to fill more of every row in this one call. `engagement` fills `post.engagement.views`, `.likes` and `.comments`, `post.content.duration_seconds`, `post.ext.channel_id` and `post.author.display_name` where the row lacks them, and replaces a date derived from a label such as \"4 months ago\" with the exact publish time (removing `post.ext.published_precision`). `channel` puts the channel's subscriber count on `post.ext.author_followers` (YouTube's own figure, which it rounds to three significant figures above 1,000) and fills the channel's `post.author.display_name`, `.avatar_url` and `.username` where missing. It also adds the country the channel's owner set, as an ISO 3166-1 alpha-2 code on `post.ext.author_country` (null when the channel sets none). Send both to cover rows that arrive without a channel id: the video join supplies it and the channel join then uses it. Each join costs 1 credit per distinct video or channel it filled, and never more than 5 per 50; ids that could not be filled are refunded. Each join adds 0.2 to 0.7 seconds on a fresh page (one lookup per 50 ids, never more than 8 seconds). Read `data.hydration` for the rows, lookups, credits held and kept, and the time.", "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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/playlist/items" }, "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": "youtube", "endpoint": "/v1/youtube/playlist/items", "data": { "items": [ { "post": { "id": "fOT0BUpITw8", "url": "https://www.youtube.com/watch?v=fOT0BUpITw8", "content": { "text": "Sample comment text (redacted).", "media_urls": null, "thumbnail_url": "https://i.ytimg.com/vi/fOT0BUpITw8/hqdefault.jpg", "duration_seconds": null }, "author": { "username": null, "display_name": "user_ddb04b", "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": "2023-12-08T00:00:10.000Z", "ext": { "position": 0, "playlistId": "PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI", "videoOwnerChannelId": "UCzrM_068Odho89mTRrrxqbA", "videoPublishedAt": "2023-12-08T00:00:10Z", "description": "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).", "playlist_item_id": "UExGZ3F1TG5MNTlhbENsXzJUUXZPaUQ1VmdtMWhDYUdTSS4xMzQwRkNFMjRDQTBENkE5", "playlist_owner_channel_id": "UC-9-kyTW8ZkZNDHQJ6FgpwQ", "playlist_owner_title": "Music", "channel_id": "UCzrM_068Odho89mTRrrxqbA" } }, "computed": { "engagement_rate": null, "language": null, "content_category": "other", "estimated_reach": null } }, { "post": { "id": "NFvDHYMzj9U", "url": "https://www.youtube.com/watch?v=NFvDHYMzj9U", "content": { "text": "Sample comment text (redacted).", "media_urls": null, "thumbnail_url": "https://i.ytimg.com/vi/NFvDHYMzj9U/hqdefault.jpg", "duration_seconds": null }, "author": { "username": null, "display_name": "user_fc9a62", "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": "2023-12-11T00:40:36.000Z", "ext": { "position": 1, "playlistId": "PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI", "videoOwnerChannelId": "UCu4bj03KW4CwAsYtHSwMEsQ", "videoPublishedAt": "2023-12-11T00:40:36Z", "description": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "playlist_item_id": "UExGZ3F1TG5MNTlhbENsXzJUUXZPaUQ1VmdtMWhDYUdTSS5EQTk2NDZBREE3RjAxNDRC", "playlist_owner_channel_id": "UC-9-kyTW8ZkZNDHQJ6FgpwQ", "playlist_owner_title": "Music", "channel_id": "UCu4bj03KW4CwAsYtHSwMEsQ" } }, "computed": { "engagement_rate": null, "language": null, "content_category": "other", "estimated_reach": null } } ], "next_cursor": "EAAaHlBUOkNESWlFRGRCUWtJek1UWkdRVEpGUXprM01qSQ", "total": 183, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiRUFBYUhsQlVPa05FU1dsRlJHUkNVV3RKZWsxVVdrZFJWRXBHVVhwck0wMXFTUSIsImUiOiJ5b3V0dWJlL3BsYXlsaXN0L2l0ZW1zIiwicCI6ImN1cnNvciJ9", "has_more": true, "page_size": 50 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T07:30:20.143Z", "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" } } } } } } }, "/youtube/search/advanced": { "get": { "summary": "Advanced YouTube video search", "description": "Searches YouTube videos with the full filter set: sort `order`, `duration`, live/upcoming `event_type`, Creative-Commons `license`, `category`, `region`, `language`, and `published_after`/`published_before` date windows: returning video id, title, thumbnail, channel, and publish time, plus a `cursor` for the next page. Results are always videos. This is the reliable lane for date-window, sort, and page-size work. `published_after`/`published_before` take exact RFC-3339 bounds and are genuinely applied (`/v1/youtube/search`'s coarse `uploadDate` buckets are silently dropped by that upstream whenever a `type` is also set); `order=date` is an exact sort (measured: zero inversions); `order=viewCount` is YouTube's popularity-weighted ranking: strongly view-correlated with the top result leading, but not strictly descending, so with `includeExtras=true` sort the page client-side on `engagement.views` for exact ranking (the counts are in the response); and `max_results` returns up to the page size you ask for, 1-50 (exact when YouTube has the supply). Every result carries an exact per-second `published_at`. Set `includeExtras=true` to add view/like/comment counts and `duration_seconds` to every result (+5 credits per page), without it those are null, because YouTube's search index returns snippets only. Send `include=channel` to add each result's channel subscriber count (`post.ext.author_followers`) in the same call (1 credit per distinct channel, at most 5 per page); the two combine. SHORTS: there is no `type=shorts` here and there cannot be. YouTube's Data API has no Shorts concept, so no filter can distinguish a vertical Short from any other video. The documented APPROXIMATION is `duration=short` (under 4 minutes) plus `includeExtras=true` and a client-side filter on `post.content.duration_seconds <= 180`; it will include short landscape videos, so treat it as a narrowing heuristic, not a Shorts filter. For a real Shorts shelf use `/v1/youtube/search?type=shorts`, which reads YouTube's own Shorts surface and carries its own caveats.", "tags": [ "youtube" ], "operationId": "get_youtube_search_advanced", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 11, "x-credit-cost-formula": "1 credit for the search page. `includeExtras=true` adds a flat 5 credits for the single hydration call that fills view, like and comment counts and `duration_seconds` on the whole page. The increment never repeats: the page caps at 50 results, which one hydration call covers, so a hydrated page of 50 costs 6 credits and so does a hydrated page of 5. include=channel adds 1 credit per distinct channel filled, at most 5 per page, with channels that could not be read refunded, so a page with both is at most 11 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 query.", "schema": { "type": "string" }, "example": "lofi hip hop" }, { "name": "order", "in": "query", "required": false, "description": "Sort order: date, rating, relevance (default), title, videoCount, viewCount. `order=date` is exact (measured: zero inversions against the timestamps). `order=viewCount` is YouTube's popularity-weighted ranking: the top result is the true maximum but mid-list order is approximate, so for exact ranking add `includeExtras=true` and sort the page on `engagement.views` client-side. Both are far more faithful than `/v1/youtube/search`'s `sortBy=popular`, which is not view-ordered at all.", "schema": { "type": "string" } }, { "name": "duration", "in": "query", "required": false, "description": "Video length: short (<4m), medium (4-20m), long (>20m), any. Genuinely applied (unlike `/v1/youtube/search`'s `duration`, which the upstream ignores). `short` plus a client-side `post.content.duration_seconds <= 180` filter is the documented Shorts approximation: see the endpoint description for why it is an approximation and not a Shorts filter.", "schema": { "type": "string" }, "example": "long" }, { "name": "event_type", "in": "query", "required": false, "description": "Broadcast type: live, upcoming, completed.", "schema": { "type": "string" } }, { "name": "license", "in": "query", "required": false, "description": "License filter: creativeCommon, youtube, any.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "YouTube video category id (e.g. 10 = Music).", "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "description": "ISO 3166-1 alpha-2 country code.", "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "description": "Preferred result language (ISO 639-1).", "schema": { "type": "string" } }, { "name": "published_after", "in": "query", "required": false, "description": "RFC-3339 datetime lower bound (e.g. 2026-01-01T00:00:00Z). Exact and genuinely applied. This is the endpoint to use for date-window work.", "schema": { "type": "string" } }, { "name": "published_before", "in": "query", "required": false, "description": "RFC-3339 datetime upper bound. Exact and genuinely applied.", "schema": { "type": "string" } }, { "name": "channel_id", "in": "query", "required": false, "description": "Restrict results to a single channel id.", "schema": { "type": "string" } }, { "name": "max_results", "in": "query", "required": false, "description": "Maximum number of videos to return (1-50). Honored exactly: a page of 50 returns 50 (live-verified).", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous response: fetches the next page.", "schema": { "type": "string" } }, { "name": "safe_search", "in": "query", "required": false, "description": "Safe-search filter: none, moderate, strict.", "schema": { "type": "string" } }, { "name": "video_caption", "in": "query", "required": false, "description": "Caption filter: any, closedCaption, none.", "schema": { "type": "string" } }, { "name": "video_definition", "in": "query", "required": false, "description": "Quality filter: any, high, standard.", "schema": { "type": "string" } }, { "name": "video_dimension", "in": "query", "required": false, "description": "Dimension filter: 2d, 3d, any.", "schema": { "type": "string" } }, { "name": "video_embeddable", "in": "query", "required": false, "description": "Restrict to embeddable videos: true, any.", "schema": { "type": "string" } }, { "name": "video_type", "in": "query", "required": false, "description": "Type filter: any, episode, movie.", "schema": { "type": "string" } }, { "name": "topic_id", "in": "query", "required": false, "description": "Restrict to a Freebase topic id (e.g. /m/04rlf for music).", "schema": { "type": "string" } }, { "name": "location", "in": "query", "required": false, "description": "Latitude,longitude center for a geo search (e.g. 37.42307,-122.08427). Must be used together with location_radius.", "schema": { "type": "string" } }, { "name": "location_radius", "in": "query", "required": false, "description": "Radius around location with a unit suffix (e.g. 50km, 10mi). Must be used together with location.", "schema": { "type": "string" } }, { "name": "includeExtras", "in": "query", "required": false, "description": "Set to `true` to add the view, like and comment counts (`post.engagement.views` / `.likes` / `.comments`) and the video length (`post.content.duration_seconds`) to every result. Left off, those four are null. YouTube's search index returns snippets only, so the counts come from a second lookup. Costs +5 credits per page (a page is at most 50 results, so it is a flat +5, not per result) and adds one upstream round-trip. If that lookup fails the page still returns, un-hydrated, with the +5 refunded and `_warnings: [\"extras_unavailable\"]` on the response.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Set to `channel` (one token only) to add each row's channel stats in this one call. `channel` puts the channel's subscriber count on `post.ext.author_followers` (YouTube's own figure, which it rounds to three significant figures above 1,000) and fills the channel's `post.author.display_name`, `.avatar_url` and `.username` where missing. It also adds the country the channel's owner set, as an ISO 3166-1 alpha-2 code on `post.ext.author_country` (null when the channel sets none). Each join costs 1 credit per distinct video or channel it filled, and never more than 5 per 50; ids that could not be filled are refunded. Each join adds 0.2 to 0.7 seconds on a fresh page (one lookup per 50 ids, never more than 8 seconds). Read `data.hydration` for the rows, lookups, credits held and kept, and the time.", "schema": { "type": "string", "enum": [ "channel" ] } }, { "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": "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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/search/advanced" }, "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": "youtube", "endpoint": "/v1/youtube/search/advanced", "data": { "items": [ { "post": { "id": "n61ULEU7CO0", "url": "https://www.youtube.com/watch?v=n61ULEU7CO0", "content": { "text": "Sample comment text (redacted).", "media_urls": null, "thumbnail_url": "https://i.ytimg.com/vi/n61ULEU7CO0/hqdefault.jpg", "duration_seconds": null }, "author": { "username": null, "display_name": "user_a34447", "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": "2021-12-31T16:30:13.000Z", "ext": { "description": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "channel_id": "UCSJ4gkVC6NrvII8umztf0Ow" } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": null } }, { "post": { "id": "CFGLoQIhmow", "url": "https://www.youtube.com/watch?v=CFGLoQIhmow", "content": { "text": "Sample comment text (redacted).", "media_urls": null, "thumbnail_url": "https://i.ytimg.com/vi/CFGLoQIhmow/hqdefault.jpg", "duration_seconds": null }, "author": { "username": null, "display_name": "user_a34447", "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": "2024-10-17T19:00:07.000Z", "ext": { "description": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "channel_id": "UCSJ4gkVC6NrvII8umztf0Ow" } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": null } } ], "next_cursor": "CAIQAA", "total": 1000000, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiQ0FJUUFBIiwiZSI6InlvdXR1YmUvc2VhcmNoL2FkdmFuY2VkIiwicCI6ImN1cnNvciJ9", "has_more": true, "page_size": 2 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T07:30:25.798Z", "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" } } } } } } }, "/youtube/search/suggestions": { "get": { "summary": "Get YouTube search suggestions", "description": "Returns YouTube's search autocomplete suggestions for a partial query: the same suggestions the search box shows. Useful for keyword expansion and SEO research. Returns a string list under `items`.", "tags": [ "youtube" ], "operationId": "get_youtube_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": "lofi" }, { "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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/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": "youtube", "endpoint": "/v1/youtube/search/suggestions", "data": { "items": [ "lofi", "lofi coffee shop" ], "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": null, "has_more": false, "page_size": 14 }, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T12:52:22.394Z", "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" } } } } } } }, "/youtube/video/audio": { "get": { "summary": "Get a YouTube video's audio file streams", "description": "Returns the downloadable audio stream files for a YouTube video: each with a direct media `url`, mime type, bitrate, audio quality, sample rate, channels, and approximate duration. The stream URLs are time-limited: fetch them immediately and do not cache.", "tags": [ "youtube" ], "operationId": "get_youtube_video_audio", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full URL of the YouTube video.", "schema": { "type": "string" }, "example": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }, { "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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/video/audio" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of media-file objects for the video (audio/video streams, subtitle tracks, or thumbnails). Each item carries the file's direct `url` plus its native technical metadata (e.g. mimeType, bitrate, quality, width/height, language). The exact fields vary by file type. This is a passthrough list, not a canonical object.", "items": { "type": "object", "description": "A single media file with a direct `url` and type-specific metadata.", "properties": { "url": { "type": "string", "description": "Direct URL to the media file. Audio/video stream URLs are time-limited: fetch immediately and do not cache." } } } }, "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": "youtube", "endpoint": "/v1/youtube/video/audio", "data": { "items": [ { "itag": 139, "url": "https://example.com/redacted", "mimeType": "audio/mp4; codecs=\"mp4a.40.5\"", "bitrate": 50152, "initRange": { "start": "0", "end": "731" }, "indexRange": { "start": "732", "end": "1027" }, "lastModified": "1766955925459591", "contentLength": "1300631", "quality": "tiny", "projectionType": "RECTANGULAR", "averageBitrate": 48813, "audioQuality": "AUDIO_QUALITY_LOW", "approxDurationMs": "213159", "audioSampleRate": "22050", "audioChannels": 2, "loudnessDb": 0.9899998, "trackAbsoluteLoudnessLkfs": -13.01, "qualityOrdinal": "QUALITY_ORDINAL_UNKNOWN", "parsedLastModified": "2025-12-28T21:05:25.459Z", "lengthSeconds": "213", "parsedContentLength": "1.24 MiB" }, { "itag": 140, "url": "https://example.com/redacted", "mimeType": "audio/mp4; codecs=\"mp4a.40.2\"", "bitrate": 130677, "initRange": { "start": "0", "end": "722" }, "indexRange": { "start": "723", "end": "1018" }, "lastModified": "1766955925572207", "contentLength": "3449447", "quality": "tiny", "projectionType": "RECTANGULAR", "averageBitrate": 129502, "highReplication": true, "audioQuality": "AUDIO_QUALITY_MEDIUM", "approxDurationMs": "213089", "audioSampleRate": "44100", "audioChannels": 2, "loudnessDb": 0.9899998, "trackAbsoluteLoudnessLkfs": -13.01, "qualityOrdinal": "QUALITY_ORDINAL_UNKNOWN", "parsedLastModified": "2025-12-28T21:05:25.572Z", "lengthSeconds": "213", "parsedContentLength": "3.29 MiB" } ], "dropped": 0 }, "credits_used": 5, "credits_remaining": 9999, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": null, "has_more": false, "page_size": 4 }, "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" } } } } } } }, "/youtube/video/files": { "get": { "summary": "Get a YouTube video's video file streams", "description": "Returns the downloadable video stream files for a YouTube video: each with a direct media `url`, mime type, resolution (`width`/`height`), quality label, fps, bitrate, and approximate duration. The stream URLs are time-limited: fetch them immediately and do not cache.", "tags": [ "youtube" ], "operationId": "get_youtube_video_files", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full URL of the YouTube video.", "schema": { "type": "string" }, "example": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }, { "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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/video/files" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of media-file objects for the video (audio/video streams, subtitle tracks, or thumbnails). Each item carries the file's direct `url` plus its native technical metadata (e.g. mimeType, bitrate, quality, width/height, language). The exact fields vary by file type. This is a passthrough list, not a canonical object.", "items": { "type": "object", "description": "A single media file with a direct `url` and type-specific metadata.", "properties": { "url": { "type": "string", "description": "Direct URL to the media file. Audio/video stream URLs are time-limited: fetch immediately and do not cache." } } } }, "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": "youtube", "endpoint": "/v1/youtube/video/files", "data": { "items": [ { "itag": 18, "url": "https://example.com/redacted", "mimeType": "video/mp4; codecs=\"avc1.42001E, mp4a.40.2\"", "bitrate": 444226, "width": 640, "height": 360, "lastModified": "1766960953317159", "quality": "medium", "fps": 25, "qualityLabel": "360p", "projectionType": "RECTANGULAR", "audioQuality": "AUDIO_QUALITY_LOW", "approxDurationMs": "213089", "audioSampleRate": "44100", "audioChannels": 2, "qualityOrdinal": "QUALITY_ORDINAL_360P", "parsedLastModified": "2025-12-28T22:29:13.317Z", "lengthSeconds": "213", "parsedContentLength": "0 Bytes" }, { "itag": 313, "url": "https://example.com/redacted", "mimeType": "video/webm; codecs=\"vp9\"", "bitrate": 18076636, "width": 3840, "height": 2160, "initRange": { "start": "0", "end": "220" }, "indexRange": { "start": "221", "end": "893" }, "lastModified": "1766963492248817", "contentLength": "358608461", "quality": "hd2160", "fps": 25, "qualityLabel": "2160p", "projectionType": "RECTANGULAR", "averageBitrate": 13466333, "colorInfo": { "primaries": "COLOR_PRIMARIES_BT709", "transferCharacteristics": "COLOR_TRANSFER_CHARACTERISTICS_BT709", "matrixCoefficients": "COLOR_MATRIX_COEFFICIENTS_BT709" }, "approxDurationMs": "213040", "qualityOrdinal": "QUALITY_ORDINAL_2160P", "parsedLastModified": "2025-12-28T23:11:32.248Z", "lengthSeconds": "213", "parsedContentLength": "342 MiB" } ], "dropped": 0 }, "credits_used": 5, "credits_remaining": 9999, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": null, "has_more": false, "page_size": 23 }, "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" } } } } } } }, "/youtube/video/subtitles": { "get": { "summary": "Get a YouTube video's subtitle files", "description": "Returns the downloadable subtitle/caption track files for a YouTube video: each with a language code and name, format, and a direct download `url`. Includes both manual and auto-generated tracks across available subtitle formats (srt, vtt, ttml, …).", "tags": [ "youtube" ], "operationId": "get_youtube_video_subtitles", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full URL of the YouTube video.", "schema": { "type": "string" }, "example": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }, { "name": "format", "in": "query", "required": false, "description": "Subtitle file format filter (e.g. srt, vtt, ttml, json3, srv1).", "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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/video/subtitles" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of media-file objects for the video (audio/video streams, subtitle tracks, or thumbnails). Each item carries the file's direct `url` plus its native technical metadata (e.g. mimeType, bitrate, quality, width/height, language). The exact fields vary by file type. This is a passthrough list, not a canonical object.", "items": { "type": "object", "description": "A single media file with a direct `url` and type-specific metadata.", "properties": { "url": { "type": "string", "description": "Direct URL to the media file. Audio/video stream URLs are time-limited: fetch immediately and do not cache." } } } }, "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": "youtube", "endpoint": "/v1/youtube/video/subtitles", "data": { "items": [ { "languageName": "English", "languageCode": "en", "format": "srt", "url": "https://example.com/redacted" }, { "languageName": "English", "languageCode": "en", "format": "vtt", "url": "https://example.com/redacted" } ], "dropped": 0 }, "credits_used": 1, "credits_remaining": 9999, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": null, "has_more": false, "page_size": 990 }, "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" } } } } } } }, "/youtube/video/thumbnails": { "get": { "summary": "Get a YouTube video's thumbnail files", "description": "Returns the thumbnail image files for a YouTube video at every available size: each with a direct image `url`, dimensions (`width`/`height`), aspect `ratio`, and image `format` (webp / jpg).", "tags": [ "youtube" ], "operationId": "get_youtube_video_thumbnails", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full URL of the YouTube video.", "schema": { "type": "string" }, "example": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }, { "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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/video/thumbnails" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of media-file objects for the video (audio/video streams, subtitle tracks, or thumbnails). Each item carries the file's direct `url` plus its native technical metadata (e.g. mimeType, bitrate, quality, width/height, language). The exact fields vary by file type. This is a passthrough list, not a canonical object.", "items": { "type": "object", "description": "A single media file with a direct `url` and type-specific metadata.", "properties": { "url": { "type": "string", "description": "Direct URL to the media file. Audio/video stream URLs are time-limited: fetch immediately and do not cache." } } } }, "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": "youtube", "endpoint": "/v1/youtube/video/thumbnails", "data": { "items": [ { "id": "default", "width": 120, "height": 90, "format": "webp", "ratio": "4:3", "url": "https://i.ytimg.com/vi_webp/dQw4w9WgXcQ/default.webp" }, { "id": "medium", "width": 320, "height": 180, "format": "webp", "ratio": "16:9", "url": "https://i.ytimg.com/vi_webp/dQw4w9WgXcQ/mqdefault.webp" } ], "dropped": 0 }, "credits_used": 1, "credits_remaining": 9999, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": null, "has_more": false, "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" } } } } } } }, "/youtube/profile/full": { "get": { "summary": "YouTube profile, recent posts, and computed analytics in one call.", "description": "Fans out to the YouTube 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 YouTube is up to 30 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. The videos leg is fetched with `includeExtras=true` so like and comment counts populate on the same page as views.", "tags": [ "youtube" ], "operationId": "get_youtube_profile_full", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 5, "x-socialcrawl-oneOf": [ [ "handle", "channelId", "url" ] ], "parameters": [ { "name": "handle", "in": "query", "required": false, "description": "YouTube username or handle, with or without a leading @. One of the identity params is required. (one of: handle, channelId, url; at least one required)", "schema": { "type": "string" }, "example": "mrbeast" }, { "name": "channelId", "in": "query", "required": false, "description": "YouTube channel id, the 24-character string starting with UC. One of the identity params is required. (one of: handle, channelId, url; at least one required)", "schema": { "type": "string" } }, { "name": "url", "in": "query", "required": false, "description": "Full YouTube profile or page URL. One of the identity params is required. (one of: handle, channelId, url; 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 YouTube is up to 30 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": "youtube" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/youtube/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": "youtube", "endpoint": "/v1/youtube/profile/full", "data": { "profile": { "id": "UCX6OQ3DkcsbYNE6H8uQQuVA", "username": "@mrbeast", "display_name": "MrBeast", "avatar_url": "https://yt3.ggpht.com/nxYrc_1_2f77DoBadyxMTmv7ZpRZapHR5jbuYe7PlPd5cIRJxtNNEYyOC0ZsxaDyJJzXrnJiuDE=s800-c-k-c0x00ffffff-no-rj", "bio": "SUBSCRIBE FOR A COOKIE!\nNew MrBeast or MrBeast Gaming video every single Saturday at noon eastern time!\nAccomplishments:\n- Raised $20,000,000 To Plant 20,000,000 Trees\n- Removed 30,000,000 pounds of trash from the ocean\n- Helped 2,000 people walk again\n- Helped 1,000 blind people see\n- Helped 1,000 deaf people hear\n- Built wells in Africa\n- Built and gave away 100 houses\n- Adopted every dog in a shelter (twice)\n- Given millions to charity\n- Started my own snack company Feastables\n- Started my own software company Viewstats\n- Gave away a private island (twice)\n- Gave away 1 million meals\n- I counted to 100k\n- Ran a marathon in the world's largest shoes\n- Survived 50 hours in Antarctica\n- Recreated Squid Game in real life\n- Created the largest competition show with 1000 people (Beast Games)\n- Gave $5,000,000 to one person\n- Raised $40,000,000 To Bring Clean Water To Millions Of People\n- Granted 100+ Dream Wishes for Kids Fighting Cancer\n- Gave Away Another $5,000,000 On Beast Games S2\n", "verified": null, "followers": 519000000, "following": null, "posts_count": 1004, "likes_count": null, "url": "https://www.youtube.com/channel/UCX6OQ3DkcsbYNE6H8uQQuVA", "private": null, "joined_at": "2012-02-20", "ext": { "country": "US", "public_email": null, "followers_approximate": true, "keywords": "mrbeast6000 beast mrbeast Mr.Beast mr", "total_views": 141365659160, "joined_at_timestamp": "2012-02-20T00:43:50Z", "topicCategories": [ "https://en.wikipedia.org/wiki/Lifestyle_(sociology)", "https://en.wikipedia.org/wiki/Entertainment" ], "bannerExternalUrl": "https://yt3.googleusercontent.com/mHMO_eEMp0dPvh0ADwXhPXNYb_GnjSVsLI8biqF1CpxT8OPl7izhNQsDPD3JHhd5y5Mg9GrP", "madeForKids": false, "hiddenSubscriberCount": false, "related_playlists": { "likes": "", "uploads": "UUX6OQ3DkcsbYNE6H8uQQuVA" }, "topic_ids": [ "/m/019_rr", "/m/02jjt" ], "unsubscribed_trailer": "v9QtM6qnG50" } }, "posts": [ { "post": { "id": "v9QtM6qnG50", "url": "https://www.youtube.com/watch?v=v9QtM6qnG50", "content": { "text": "I Built A City To Save Kids From Illegal Labor", "media_urls": null, "thumbnail_url": "https://i.ytimg.com/vi/v9QtM6qnG50/hq720.jpg?sqp=-oaymwEnCNAFEJQDSFryq4qpAxkIARUAAIhCGAHYAQHiAQoIGBACGAY4AUAB&rs=AOn4CLDHC3kCWybW0hDOotcH3B6Q1hT3wg", "duration_seconds": 1143 }, "author": { "username": "@MrBeast", "display_name": "MrBeast", "avatar_url": "https://example.com/redacted", "verified": null }, "engagement": { "views": 86468274, "likes": 2090602, "comments": 97000, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-19T16:00:01.000Z", "ext": { "content_type": "video", "categoryTitle": "Entertainment", "description": "Huge thanks to the 1 Billion Followers Summit, Mohammed Bin Rashid Global Initiatives, and the Varkey Foundation; the partners who believed in this vision and helped make this village a reality.\n\nClick the link to claim your free Neuro Gum Pack, valued up to $24, at Costco or Walmart here: https://try.gotoaisle.com/neuro-beast\n\nWith gratitude to The Rockefeller Foundation for providing regenerative school meals for the next five years, and for helping build the farm that grows them. https://www.rockefellerfoundation.org\n\nThanks to our friends at Global Energy Alliance, this village now runs on solar — bringing light to every home, market and community space. https://energyalliance.org\n\n190 trees were cut down to bring this village to life. Now we're working with Arbor Day Foundation, our longtime partners, to plant 250 new ones where they'll do the most good.\n\nSUB TO ALL CHANNELS\n   / @mrbeast  \n   / @mrbeast2   \n   / @mrbeastgaming   \n   / @beastreacts   \n   / @beastphilanthropy   \n   / @beastanimations   \n\nNew Merch - https://mrbeast.store\nCheck out Viewstats! - https://www.viewstats.com/\nFor any questions or inquiries regarding this video, please reach out to redacted@example.com\nMusic Provided by https://www.extrememusic.com\n----------------------------------------------------------------\nfollow all of these or i will kick you\n• Facebook -   / mrbeast  \n• Twitter -   / mrbeast  \n• Instagram -   / mrbeast  \n• Im Hiring! - https://www.mrbeastjobs.com/", "channel_id": "UCX6OQ3DkcsbYNE6H8uQQuVA", "author_id": "UCX6OQ3DkcsbYNE6H8uQQuVA" } }, "computed": { "engagement_rate": 0.025299, "language": null, "content_category": "other", "estimated_reach": 103761929 } }, { "post": { "id": "gTKS8SAwUzE", "url": "https://www.youtube.com/watch?v=gTKS8SAwUzE", "content": { "text": "I Survived The Most Extreme Places On Earth", "media_urls": null, "thumbnail_url": "https://i.ytimg.com/vi/gTKS8SAwUzE/hq720.jpg?sqp=-oaymwEnCNAFEJQDSFryq4qpAxkIARUAAIhCGAHYAQHiAQoIGBACGAY4AUAB&rs=AOn4CLCinCS-72tR3BbuXhG-OTPNG2SLgw", "duration_seconds": 1408 }, "author": { "username": "@MrBeast", "display_name": "MrBeast", "avatar_url": "https://example.com/redacted", "verified": null }, "engagement": { "views": 119053037, "likes": 1480902, "comments": 69000, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-05T16:00:01.000Z", "ext": { "content_type": "video", "categoryTitle": "Entertainment", "description": "We raced through some of the most extreme places on Earth to see who could make it to the finish line first!\n\nGemini helped us plan, problem-solve, and take on challenges along the way. Try Gemini here: https://gemini.google.com/app/downloa... GooglePartner\n\nPedialyte always comes in clutch when you need to rehydrate and feel better fast. Grab your favorite Pedialyte flavors on Amazon here https://www.amazon.com/stores/page/79... and use code BEAST40 for 40% off right now. PedialytlePartner\n\nFor anyone wondering about the backpacks we dropped at the end, don't worry! We only ditched them for a second so we could full-send it to the finish line! Our team went right back out and recovered every single piece of gear immediately after to ensure we left the environment as clean as when we got there! ❤️\n\nSUB TO ALL CHANNELS\n   / @mrbeast  \n   / @mrbeast2   \n   / @mrbeastgaming   \n   / @beastreacts   \n   / @beastphilanthropy   \n   / @beastanimations   \n\nNew Merch - https://mrbeast.store\nCheck out Viewstats! - https://www.viewstats.com/\nFor any questions or inquiries regarding this video, please reach out to redacted@example.com\nMusic Provided by https://www.extrememusic.com\n----------------------------------------------------------------\nfollow all of these or i will kick you\n• Facebook -   / mrbeast  \n• Twitter -   / mrbeast  \n• Instagram -   / mrbeast  \n• Im Hiring! - https://www.mrbeastjobs.com/", "channel_id": "UCX6OQ3DkcsbYNE6H8uQQuVA", "author_id": "UCX6OQ3DkcsbYNE6H8uQQuVA" } }, "computed": { "engagement_rate": 0.013019, "language": null, "content_category": "other", "estimated_reach": 142863644 } } ], "computed": { "avg_engagement_rate": 0.020955440000000002, "avg_engagement_rate_by_followers": 0.00523, "posts_per_week": 0.5, "cadence_window_days": 350, "top_post": { "url": "https://www.youtube.com/watch?v=Oo9EbArcQ1c", "engagement_total": 248785064 }, "format_mix": { "video": 25 } }, "posts_cursor": "4qmFsgLdCBIYVUNYNk9RM0RrY3NiWU5FNkg4dVFRdVZBGsAIOGdhbkJocWtCbnFoQmpxZUJnb2tObUkyTnpNMU9HUXRNREF3TUMweVl6QTJMVGd4TnpFdE0yTXlPRFprTXpneU1HUTJFdk1GUVdaelYydHNOVGhxTW1OdFdtOHdORVpwVjFFeGFqbHBXbHBOV1d4cldsaFRXQzF3VFZaSVFta3lZWGd0WjBsdk9XUkZVR2M1VFZwM1NETmhNbEJEWkdadFZsUkZhekJ4WTI1a2RrRmZURTE1VEVSb2JWQkRiV2RTV1VOUGNWOTNhbWxEUW5nMFJHNXZTRXRNYVRaeE0wMXBSSHBNWkcxdWJWTjVPR1V4UkhaRGFXbFVTamxtVkRaTU1IVmFObU01Y2xCVGMzcHpWMWRPU1ZKQlkwTndhVFEzVkdKRk5GWkhWR3BTUldKQ1JGbFlWMHRtVFRSdlZHUXpiVWhNY2taM1dscHhlVkpYUlRZMVQzaDBTbU5mVFRSeVFWOWZkWFZQY21ReWNrcDVNSEJIWlMxWGJsaHdiMFpSTVc0d05WQjJjWFJST0RWTWVFNUxkRFZSVWxWd2RrVkJaM0IwUjJGelZGUmZVbFJqZVhJMmFrSmlOMXBuZVZaS1ZsaHhZbXN6TVVRdFMwcExXVWxZVTJ4MGJXTkhaV1UyV0hwV1ozWmtabmc1WjFoRFVISm9TVGxhZDBkd016VnBUa054VGtOUFIyUnVRV053YVdFdFIya3RPRlZtYzNwb1dEZGpTWFo2TlVOa1pYZzNkMWRvT1hjNVJsVnphVEJNT0hNd1kzTk1hRUpEUW5aMloxcERRbE5UT0hWYVpWbEhUVFpMWlRFdFIyVXRPWGRuT1ZaaWJWUktPSEpsYUZsc1ZqVldabXAwYnpaMlJHcFlRV2xUUlhkQmVUaDBPRkJGZEZSUmVYSnBhRkEwUzBwQlJXZG5TblJ3UmtoS2EwWkZaa0Y2U2xwQ1RscG1jMkZ2UTNKRlNVeExSMlJqUWtzd01uVXRRVkJXYTA1a2RXTkJWR0UxUlVNd00xRm1aR3BvUmtoaloyNDJZMUJFVEZabVV6aG9jVUZZWjA4emMxQTVjMWd3VDNOaVFsbFZWbVJtUjBwMlVWUk5Ra2N6VWxoVlJsUXRTMDFXY0RSelZFYzVjbTEwVUcxMllsOUtVRzFVUTBOUVpTMDFVR3RSTkU5RVVuZHFMV1l6VjAxUVpsb3hlWE5WUVZoRVRFZEpiRWRVUjNGbmR6UkpPREo0YTBrMFIxaEpVMlIxVVRZMlVFTm9VekpmVlMxd1kwZDVVakZpVG1sSmVuRldNRjlYVG1kaVFrOTJiMTlSYnpaNE4ybDJTbEpJWjI5M1NUTkZRa2RpYUVVeFVWRm5abFZFUjJkNVNrTlBYMHhSUTJSQmFWWXdWMDV4TkVGRGFHYzJVR3ByUzJSclNqbEVZVFJwWmpsWlptMDBPVTBZQkElM0QlM0Q%3D", "legs": [ { "endpoint": "/v1/youtube/channel", "status": 200, "credits_used": 1, "latency_ms": 167, "error": null }, { "endpoint": "/v1/youtube/channel/user_26760e", "status": 200, "credits_used": 1, "latency_ms": 5823, "error": null } ] }, "credits_used": 5, "request_id": "req_example000000", "cached": false, "credits_remaining": 9999, "source": "captured", "captured_at": "2026-10-02T12:41:27.248Z", "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" }