{ "openapi": "3.1.0", "info": { "title": "SocialCrawl API: Facebook", "version": "1.0.0", "description": "Unified social media data API - one API key, one consistent response format, 69 platforms, 679 endpoints. Power AI agents with clean social data.\n\nThis document covers the Facebook endpoints only (31 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": "facebook", "description": "Facebook endpoints" } ], "paths": { "/facebook/profile": { "get": { "summary": "Get Facebook page profile", "description": "Returns a unified Facebook Author profile with page ID, display name, profile URL, profile image, bio (the page intro), follower count, page-like count, and creation date. Two things to know before grading on the numbers: `author.followers` is Facebook's ROUNDED public display figure (106,000,000 on the Meta page, where the exact page-like count alongside it reads 106,588,412), and `author.joined_at` is an ISO DATE (`YYYY-MM-DD`), not an instant, because Facebook publishes page creation to the day. A **business page** carries considerably more than a personal profile, and all of it rides in `author.ext`: `business_category`, `website`, `links[]`, `public_phone`, `public_email`, `address`, `price_range`, `rating` (Facebook's recommendation string, e.g. `\"74% recommend (9,493 reviews)\"`) with `rating_count` (that review count as a number), `talking_about_count`, `cover_url`, `page_active`, and `ad_library_page_id` / `ad_library_status`: the Ad Library page id is a different id from `author.id` and is the one `/v1/facebook/adlibrary/company/ads` takes, so you can chain profile → ads off a single lookup. A personal profile returns null for the listing fields it has no equivalent for rather than omitting them. `links[]` and `business_hours[]` are also mapped, the latter only when you pass `get_business_hours=true`, but Facebook returned both empty on every page measured on 2026-08-11, so treat them as best effort rather than data you can depend on. `author.following` and `author.posts_count` remain null because the upstream profile response does not provide those totals.", "tags": [ "facebook" ], "operationId": "get_facebook_profile", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full URL of the Facebook page or profile. A profile share link (`https://www.facebook.com/share/…`) is accepted.", "schema": { "type": "string" }, "example": "https://www.facebook.com/Meta" }, { "name": "get_business_hours", "in": "query", "required": false, "description": "Get the business's hours", "schema": { "type": "string" } }, { "name": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 900 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 3600 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/profile" }, "data": { "type": "object", "description": "Platform-specific response data", "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": [ "number", "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": [ "number", "null" ], "description": "Number of accounts followed" }, "posts_count": { "type": [ "number", "null" ], "description": "Total number of posts / videos / tracks / episodes" }, "likes_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at author.ext.employee_count_range.start" }, "end": { "type": [ "number", "null" ], "description": "Numeric at author.ext.employee_count_range.end" } } }, "founded_year": { "type": [ "number", "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": [ "object", "null" ], "description": "Object at author.ext.headquarters" }, "locations": { "type": [ "array", "null" ], "description": "Array at author.ext.locations", "items": { "description": "Leaf at author.ext.locations" } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at author.ext.hashtags", "items": { "description": "Leaf at author.ext.hashtags" } }, "funding": { "type": [ "object", "null" ], "description": "Object 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": [ "number", "null" ], "description": "Numeric at author.ext.rating_count" }, "talking_about_count": { "type": [ "number", "null" ], "description": "Numeric at author.ext.talking_about_count" }, "business_hours": { "type": [ "array", "null" ], "description": "Array at author.ext.business_hours", "items": { "description": "Leaf at author.ext.business_hours" } }, "links": { "type": [ "array", "null" ], "description": "Array at author.ext.links", "items": { "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" ], "enum": [ "app", "web", 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": [ "number", "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": [ "object", "null" ], "description": "Object 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": [ "object", "null" ], "description": "Object at author.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: author.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at author.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at author.ext.localizations.*.description" } } } }, "monthly_listeners": { "type": [ "number", "null" ], "description": "Numeric at author.ext.monthly_listeners" }, "total_ratings": { "type": [ "number", "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": [ "number", "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": "object", "description": "Object at author.ext.rules" } }, "weekly_active_users": { "type": [ "number", "null" ], "description": "Numeric at author.ext.weekly_active_users" }, "weekly_contributions": { "type": [ "number", "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": [ "number", "null" ], "description": "Numeric at author.ext.post_karma" }, "comment_karma": { "type": [ "number", "null" ], "description": "Numeric at author.ext.comment_karma" }, "awardee_karma": { "type": [ "number", "null" ], "description": "Numeric at author.ext.awardee_karma" }, "trophy_count": { "type": [ "number", "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": { "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": [ "object", "null" ], "description": "Object at author.ext.group" }, "search_hit": { "type": [ "object", "null" ], "description": "Nested object: author.ext.search_hit", "properties": { "match": { "type": [ "string", "null" ], "enum": [ "group_page", "post_in_group", "channel_page", "post_in_channel", 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": [ "number", "null" ], "description": "Numeric at author.ext.visitors_today" }, "visitors_total": { "type": [ "number", "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" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "number", "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": [ "number", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "number", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "number", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "enum": [ "target", "other_named_thing", "generic_word", "not_present" ], "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "number", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "number", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "string", "boolean", "null" ], "description": "Union: number | string | boolean" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } } } }, "_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": [ "author" ] }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/profile", "data": { "author": { "id": "100080376596424", "username": "Meta", "display_name": "Meta", "avatar_url": "https://scontent-hou1-1.xx.fbcdn.net/v/t39.30808-1/825292571_1146841521338390_8821495995170295283_n.jpg?stp=c0.11.852.852a_cp6_dst-jpg_tt6&cstp=mx852x852&ctp=s480x480&_nc_cat=1&ccb=1-7&_nc_sid=2d3e12&_nc_ohc=idzu8UNXz1IQ7kNvwHhC0C8&_nc_oc=AdqNhRJL8z_YtPHACsto0Boytx2ija-r7Jhr5KdgfXTMphnePVaEk6tgYfBemFxsw70&_nc_zt=24&_nc_ht=scontent-hou1-1.xx&_nc_gid=bFVpq5p-rF2pZsdu_C6r2w&_nc_ss=78289&oh=00_AQPibNoQSJp3Er77__ctuG8mFX5zTYsJ_W21HL1hjbXxLA&oe=6AC5A181", "bio": "Connect with what you love to make things happen.", "verified": null, "followers": 106000000, "following": null, "posts_count": null, "likes_count": 106755832, "url": "https://www.facebook.com/Meta", "private": null, "joined_at": "2020-01-31", "ext": { "public_email": null, "public_phone": null, "business_category": "Company", "website": "https://www.meta.com/connect/", "cover_url": "https://scontent-hou1-1.xx.fbcdn.net/v/t39.30808-6/825292146_1146841188005090_7443674991975795954_n.jpg?stp=cp6_dst-jpg_tt6&cstp=mx3366x1246&ctp=p720x720&_nc_cat=108&ccb=1-7&_nc_sid=cc71e4&_nc_ohc=vncXg57GIL0Q7kNvwExY470&_nc_oc=AdoGlOyFynBhNfZulWq68_SISVnbpQM7q_MAgZ4qAYATRtumC56KvTUGBv58hCJlMQ0&_nc_zt=23&_nc_ht=scontent-hou1-1.xx&_nc_gid=bFVpq5p-rF2pZsdu_C6r2w&_nc_ss=78289&oh=00_AQN8jjJgo9Y_qHTjRRovLbVN5LdH9vbDbAHjT7NicpGwbw&oe=6AC59930", "page_active": false, "address": null, "price_range": null, "rating": "74% recommend (9,653 reviews)", "rating_count": 9653, "talking_about_count": 807057, "business_hours": null, "links": [ "https://www.instagram.com/meta" ], "ad_library_page_id": "108824017345866", "ad_library_status": "This Page is currently running ads.", "followers_approximate": true } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": null }, "_warnings": [ "computed.engagement_rate: author ratio exceeded 1.0 (raw: 1.00713); returned null. A lifetime likes/followers ratio is not a real engagement rate" ] }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/profile/posts": { "get": { "summary": "List Facebook page posts", "description": "Returns a list of recent posts from a Facebook page or profile. Each post includes the post text, like count, comment count, media attachments, the publish timestamp, and the per-reaction breakdown on `post.ext.reaction_counts` (`[{type, count}]`, highest first). Facebook publishes a post's share count, and a reel's exact view count and duration, on the individual post only, not on the feed, so on a plain call `post.engagement.shares` is null on every row and `post.engagement.views` and `post.content.duration_seconds` are null on reels. Send `include=engagement` and every row is joined, in the same call, to the per-post lookup that carries them: the share count lands on each row, and the exact view count and duration on each reel. The reaction counts and the publish time the feed already carries are never replaced, and a row that links to an event rather than a post is not looked up. Cost: 1 credit for the page plus 1 credit per row filled from a fresh lookup (3 rows a page, so 4 credits at most); rows already in cache are filled for free, rows that could not be filled are refunded, and a repeat of the same call within the cache window is 0 credits. Time: `include=engagement` adds 2 to 7 seconds on a fresh page (the lookups run in parallel and the call waits for the slowest, never more than 12 seconds) and nothing when the rows are already cached. The response carries a `hydration` block itemising rows, lookups, cache hits, credits and milliseconds. Facebook serves this feed in small slices, so the first response is a window onto the page rather than everything it has: `pagination.page_size` reports how many posts that window held, and deeper history is a cursor walk. Send `pagination.next_cursor` back as `cursor` and repeat until `pagination.has_more` is false; each page costs 1 credit (plus the join when you ask for it), so depth is bounded by how many pages you buy. `recent_days=N` keeps only posts from the last N days and ends the walk once a page reaches older posts; it does not change the price of a page.", "tags": [ "facebook" ], "operationId": "get_facebook_profile_posts", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 4, "x-credit-cost-formula": "1 credit for the page. include=engagement holds 1 credit per row (3 rows a page) and keeps only the rows filled from a fresh lookup, so a page is at most 4 credits; rows served from cache are free, unfilled rows 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.", "x-socialcrawl-oneOf": [ [ "url", "pageId" ] ], "parameters": [ { "name": "since", "in": "query", "required": false, "description": "Only posts published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Older posts 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 posts 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 post you already hold. The page stops just before it: that post and everything after it are left off, `next_cursor` is not returned, and `pagination.stopped_at` is `known_id`. A pinned post 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": "url", "in": "query", "required": false, "description": "Full URL of the Facebook page or profile to fetch posts for. A profile share link (`https://www.facebook.com/share/…`) is accepted. (one of: url, pageId; at least one required)", "schema": { "type": "string" }, "example": "https://www.facebook.com/Meta" }, { "name": "pageId", "in": "query", "required": false, "description": "Facebook profile page id (one of: url, pageId; at least one required)", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "To paginate through the posts", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Set to `engagement` (one token only) to fill `post.engagement.shares` on every row, and `post.engagement.views` and `post.content.duration_seconds` on reels, in this one call. Holds 1 credit per row (3 a page) and keeps only the rows filled from a fresh lookup: rows already in cache and rows the lookup cannot fill are refunded, and a row with no public share count stays null and is free, so a page is never more than 4 credits and the usual bill is lower. A row that links to an event rather than a post is not looked up. The join takes 2 to 7 seconds on a fresh page, never more than 12, and nothing when the rows are already cached; read `data.hydration` for the rows, the credits held and kept, and the time. Without it the call is unchanged.", "schema": { "type": "string", "enum": [ "engagement" ] } }, { "name": "recent_days", "in": "query", "required": false, "description": "Keep only posts published in the last N days (1 to 3650) and stop pagination once a page reaches older posts. Does not change the price of a page.", "schema": { "type": "integer", "minimum": 1, "maximum": 3650 } }, { "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": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 600 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 3600 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/profile/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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "number", "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": [ "number", "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": [ "number", "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", "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "number", "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; discover reads a country from it into `geo.country` (`source: author_location`). 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": [ "number", "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" }, "link_domain": { "type": [ "string", "null" ], "description": "String at post.ext.link_domain" }, "upvote_ratio": { "type": [ "number", "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" ], "enum": [ "video", "short", "live", "channel", "playlist", 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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "enum": [ "image", "video", "carousel", 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": [ "number", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": { "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": { "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": [ "object", "null" ], "description": "Object 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": { "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/profile/posts`, `/v1/instagram/profile/reels`, `/v1/instagram/search/reels`, `/v1/tiktok/profile/videos` 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": [ "object", "null" ], "description": "Object 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", "enum": [ "image", "video" ], "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "number", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "number", "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": [ "number", "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": [ "object", "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": [ "object", "null" ], "description": "Object at post.ext.retweeted_post" }, "quote_count": { "type": [ "number", "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": { "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": [ "object", "null" ], "description": "Object 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": "object", "description": "Object 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": [ "number", "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": [ "object", "null" ], "description": "Object at post.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: post.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.description" } } } }, "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" ], "enum": [ "minute", "hour", "day", "week", "month", "year", 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": [ "number", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "number", "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": [ "object", "null" ], "description": "Object 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": [ "number", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "object", "null" ], "description": "Object at post.ext.dsp_ids", "additionalProperties": { "type": "string", "description": "String 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": "object", "description": "Object at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "object", "description": "Object at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "object", "description": "Object 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": [ "object", "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": [ "object", "null" ], "description": "Object 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": [ "number", "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": "number", "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": [ "object", "null" ], "description": "Object at post.ext.event" }, "trend": { "type": [ "object", "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" }, "numeric_id": { "type": [ "number", "null" ], "description": "Numeric at post.ext.numeric_id" }, "outbound_url": { "type": [ "string", "null" ], "description": "String at post.ext.outbound_url" }, "group": { "type": [ "object", "null" ], "description": "Object at post.ext.group" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "number", "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": [ "number", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "number", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "number", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "enum": [ "target", "other_named_thing", "generic_word", "not_present" ], "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "number", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "number", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "string", "boolean", "null" ], "description": "Union: number | string | boolean" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } }, "vs_creator": { "type": "object", "description": "How this post performed against the creator's other posts on the page. Divides this post's views (or likes, where the platform publishes no views, as on Instagram photos and carousels) by the median of the other posts of the same media type. Costs nothing and uses no model.", "properties": { "ratio": { "type": [ "number", "null" ], "description": "This post's metric divided by the median of its peers, rounded to two decimals. 1 is typical for this creator. Null when `reason` says why no ratio was worked out.", "example": 1.8 }, "metric": { "type": [ "string", "null" ], "enum": [ "views", "likes", null ], "description": "The metric the ratio compares. Null when the row has none.", "example": "views" }, "reason": { "type": [ "string", "null" ], "enum": [ null, "pinned", "too_young", "no_peers", "median_zero", "no_metric" ], "description": "Null when a ratio was worked out. Otherwise why not: `pinned` (pinned posts are excluded), `too_young` (under 48 hours old), `no_peers` (no other post of the same media type to compare with), `median_zero` (the peers' median is 0) or `no_metric` (the row has no views or likes).", "example": null } }, "required": [ "ratio", "metric", "reason" ] } } } } } }, "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." }, "walk": { "type": "object", "description": "Present when the request sent a row-walk param (`max_pages` above 1, `max_items`, `max_credits`, a row filter, `sort_rows` or `seen`). What the walk did across the pages it fetched. Each page is billed as one call, and its charge is recorded under its own request id.", "properties": { "pages": { "type": "integer", "description": "Pages fetched.", "example": 3 }, "stopped": { "type": "string", "enum": [ "end", "max_pages", "max_items", "max_credits", "time_budget", "page_error" ], "description": "Why the walk stopped. `end`: the list ran out. `max_pages`, `max_items` or `max_credits`: the limit you set was reached. `time_budget`: the request's time budget ran low. `page_error`: a later page failed. Unless it is `end`, `pagination.next_cursor` continues from where the walk stopped.", "example": "max_pages" }, "rows_fetched": { "type": "integer", "description": "Rows read across every page, before any filter.", "example": 60 }, "rows_returned": { "type": "integer", "description": "Rows in `data.items`.", "example": 41 }, "discarded": { "type": "object", "description": "Present when you sent a row filter. Rows the filters removed, counted once each under the first filter they failed. A row a filter cannot verify (no view count, no date, no country) is discarded.", "properties": { "views_below_min": { "type": "integer", "description": "Rows with fewer views than `min_views`." }, "views_unknown": { "type": "integer", "description": "Rows with no view count, when `min_views` was sent." }, "older_than_max_age": { "type": "integer", "description": "Rows published before the `max_age_days` window." }, "date_unknown": { "type": "integer", "description": "Rows with no publish date, when `max_age_days` was sent." }, "country_not_included": { "type": "integer", "description": "Rows registered to a country that is not in `country`." }, "country_unknown": { "type": "integer", "description": "Rows with no country, when `country` was sent." }, "country_excluded": { "type": "integer", "description": "Rows registered to a country listed in `exclude_country`." } } }, "repeats": { "type": "integer", "description": "Present when you sent `seen`: rows removed because your account already received them under that id." }, "duplicates": { "type": "integer", "description": "Present when above zero: rows a later page repeated from an earlier page of the same walk, kept once." }, "credits": { "type": "object", "description": "What the pages cost.", "properties": { "pages": { "type": "integer", "description": "Credits charged for the pages walked, before refunds." }, "refunded": { "type": "integer", "description": "Credits refunded across the pages." } } }, "request_ids": { "type": "array", "description": "The request id of each page walked. Each is its own entry in `GET /v1/credits/transactions`.", "items": { "type": "string", "description": "A row id." } } } }, "hydration": { "type": "object", "description": "Present when the request asked for a row join with `include=`, or sent a param that implies one. What the join did and what it cost. On a multi-page walk it sums every page. A join that always runs for free is left out.", "properties": { "include": { "type": "string", "description": "The token that switched the join on.", "example": "profile" }, "implied_by": { "type": "string", "description": "Present when you did not send `include` and another param switched the join on. The join's credits (`extra_credits`) are then part of `credits_used`. Absent when you sent `include` yourself." }, "rows": { "type": "integer", "description": "Rows on the page after any row cap.", "example": 20 }, "looked_up": { "type": "integer", "description": "Rows that needed a lookup (at least one field the join fills was empty).", "example": 20 }, "filled": { "type": "integer", "description": "Rows where at least one field was filled by the join.", "example": 18 }, "cached": { "type": "integer", "description": "Of `filled`, rows filled from the sibling endpoint's cache at no charge.", "example": 0 }, "unfilled": { "type": "integer", "description": "Rows that needed a lookup and were not filled (the lookup failed, was skipped, or had nothing to copy). Their credits are refunded.", "example": 2 }, "credits_held": { "type": "integer", "description": "Credits held up front for the join, on top of the page's own price.", "example": 20 }, "extra_credits": { "type": "integer", "description": "Of `credits_held`, the credits kept: one lookup's price for each distinct key filled from a fresh lookup. The rest was refunded.", "example": 18 }, "ms": { "type": "integer", "description": "Time the join added, in milliseconds.", "example": 2400 }, "cached_page": { "type": "boolean", "description": "True when the whole page was served from cache, so the join cost nothing on this call.", "example": true }, "batches": { "type": "integer", "description": "Joins that look rows up in batches only: how many batch calls were made. Absent on a join that looks rows up one by one." }, "from_earlier_pages": { "type": "integer", "description": "`max_pages`, `max_items` and `max_credits` walks only: rows filled free from a key already looked up on an earlier page of the same walk. Not counted in `looked_up`, `filled` or `cached`. Absent when zero." }, "steps": { "type": "array", "description": "Present when the request asked for more than one join (`include=engagement,channel`): one report per join, in the order they ran. The top-level numbers are then the page's: rows looked up or filled by any join, and the credits and time of all of them together.", "items": { "type": "object", "description": "One join's report.", "properties": { "include": { "type": "string", "description": "The token that switched the join on.", "example": "profile" }, "implied_by": { "type": "string", "description": "Present when you did not send `include` and another param switched the join on. The join's credits (`extra_credits`) are then part of `credits_used`. Absent when you sent `include` yourself." }, "rows": { "type": "integer", "description": "Rows on the page after any row cap.", "example": 20 }, "looked_up": { "type": "integer", "description": "Rows that needed a lookup (at least one field the join fills was empty).", "example": 20 }, "filled": { "type": "integer", "description": "Rows where at least one field was filled by the join.", "example": 18 }, "cached": { "type": "integer", "description": "Of `filled`, rows filled from the sibling endpoint's cache at no charge.", "example": 0 }, "unfilled": { "type": "integer", "description": "Rows that needed a lookup and were not filled (the lookup failed, was skipped, or had nothing to copy). Their credits are refunded.", "example": 2 }, "credits_held": { "type": "integer", "description": "Credits held up front for the join, on top of the page's own price.", "example": 20 }, "extra_credits": { "type": "integer", "description": "Of `credits_held`, the credits kept: one lookup's price for each distinct key filled from a fresh lookup. The rest was refunded.", "example": 18 }, "ms": { "type": "integer", "description": "Time the join added, in milliseconds.", "example": 2400 }, "cached_page": { "type": "boolean", "description": "True when the whole page was served from cache, so the join cost nothing on this call.", "example": true }, "batches": { "type": "integer", "description": "Joins that look rows up in batches only: how many batch calls were made. Absent on a join that looks rows up one by one." }, "from_earlier_pages": { "type": "integer", "description": "`max_pages`, `max_items` and `max_credits` walks only: rows filled free from a key already looked up on an earlier page of the same walk. Not counted in `looked_up`, `filled` or `cached`. Absent when zero." } } } } } }, "creator_baseline": { "type": "object", "description": "A creator's own recent posts as a baseline. The medians of the rows on this page that entered the comparison behind `computed.vs_creator`. Pinned posts and posts under 48 hours old are excluded. Costs nothing and uses no model.", "properties": { "baseline": { "type": [ "object", "null" ], "description": "The medians, or null with `reason: fewer_than_eight` when fewer than eight rows could be compared.", "properties": { "rows_used": { "type": "integer", "description": "Rows the medians are taken over.", "example": 24 }, "median_views": { "type": [ "number", "null" ], "description": "Median view count, or null when no row has one." }, "median_likes": { "type": [ "number", "null" ], "description": "Median like count, or null when no row has one." }, "median_comments": { "type": [ "number", "null" ], "description": "Median comment count, or null when no row has one." }, "median_gap_hours": { "type": [ "number", "null" ], "description": "Median hours between posts. Null when `cadence` is `omitted`." }, "median_saves_per_view": { "type": [ "number", "null" ], "description": "Median of saves divided by views, over rows that have both." }, "median_shares_per_view": { "type": [ "number", "null" ], "description": "Median of shares divided by views, over rows that have both." } } }, "reason": { "type": [ "string", "null" ], "enum": [ "fewer_than_eight", null ], "description": "`fewer_than_eight` when there were not enough comparable rows for a baseline, otherwise null.", "example": null }, "rows_used": { "type": "integer", "description": "Rows that entered the comparison (not pinned, old enough, and carrying a metric).", "example": 24 }, "cadence": { "type": "string", "enum": [ "measured", "omitted" ], "description": "`omitted` when the publish dates are estimates, as on YouTube without `includeExtras=true`, so `median_gap_hours` is null.", "example": "measured" } } }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/profile/posts", "data": { "items": [ { "post": { "id": "1152729184082957", "url": "https://www.facebook.com/reel/2277713513083702/", "content": { "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "media_urls": "https://scontent-lga3-1.xx.fbcdn.net/v/t15.5256-10/832662077_1745304503394391_8093661530441784354_n.jpg?stp=dst-jpg_p565x565_tt6&_nc_cat=103&ccb=1-7&_nc_sid=d2b52d&_nc_ohc=NDpCrzBK770Q7kNvwGyaeJt&_nc_oc=AdrlDwjddcMXqYC3gX6XsTrZH9z3JR3ee1h_h5iPdUL9ECVaeUwmhJJEmPO0gopqyhg&_nc_zt=23&_nc_ht=scontent-lga3-1.xx&_nc_gid=MjqYFXS4EsUT7fF7gV3ocQ&_nc_ss=78289&oh=00_AQMiv1syHdc2xvm30zds_d5trO179vjqkC_6qS9P7TLoXQ&oe=6AC5130A", "thumbnail_url": "https://scontent-lga3-1.xx.fbcdn.net/v/t15.5256-10/832662077_1745304503394391_8093661530441784354_n.jpg?stp=dst-jpg_s960x960_tt6&_nc_cat=103&ccb=1-7&_nc_sid=be8305&_nc_ohc=NDpCrzBK770Q7kNvwGyaeJt&_nc_oc=AdrlDwjddcMXqYC3gX6XsTrZH9z3JR3ee1h_h5iPdUL9ECVaeUwmhJJEmPO0gopqyhg&_nc_zt=23&_nc_ht=scontent-lga3-1.xx&_nc_gid=MjqYFXS4EsUT7fF7gV3ocQ&_nc_ss=78289&oh=00_AQPNf5IOq8IR_YiMnPpsA9ilDVJU5hDGRMgC8AQY_Fvxkw&oe=6AC5130A", "duration_seconds": null }, "author": { "username": null, "display_name": "Meta", "avatar_url": null, "verified": null }, "engagement": { "views": null, "likes": 666, "comments": 191, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-10-01T16:17:21.000Z", "ext": { "author_id": "user_9cf871", "published_at_epoch": 1790871441, "reaction_counts": [ { "type": "like", "count": 561 }, { "type": "love", "count": 84 } ], "feedback_id": "ZmVlZGJhY2s6MTE1MjcyOTE4NDA4Mjk1Nw==" } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": null, "vs_creator": { "ratio": null, "metric": "likes", "reason": "too_young" } } }, { "post": { "id": "1151655277523681", "url": "https://www.facebook.com/reel/1737837581070505/", "content": { "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "media_urls": "https://scontent-lga3-3.xx.fbcdn.net/v/t15.5256-10/830096675_1581575039848247_6418634667320817606_n.jpg?stp=dst-jpg_p552x414_tt6&_nc_cat=102&ccb=1-7&_nc_sid=d2b52d&_nc_ohc=MikVnzHxCtMQ7kNvwF5Wlzv&_nc_oc=AdqFvEv4rM_9wvNx35Lpz6NrivM-TGsYbrkNRtbfR0sqmcqj0k2uHr_jD_K27NQ0mbI&_nc_zt=23&_nc_ht=scontent-lga3-3.xx&_nc_gid=MjqYFXS4EsUT7fF7gV3ocQ&_nc_ss=78289&oh=00_AQMvH1vCUl5wxaWGOy1DLqCVaqxlAyQdmnWgHKimeTEZYw&oe=6AC51880", "thumbnail_url": "https://scontent-lga3-3.xx.fbcdn.net/v/t15.5256-10/830096675_1581575039848247_6418634667320817606_n.jpg?stp=dst-jpg_s960x960_tt6&_nc_cat=102&ccb=1-7&_nc_sid=be8305&_nc_ohc=MikVnzHxCtMQ7kNvwF5Wlzv&_nc_oc=AdqFvEv4rM_9wvNx35Lpz6NrivM-TGsYbrkNRtbfR0sqmcqj0k2uHr_jD_K27NQ0mbI&_nc_zt=23&_nc_ht=scontent-lga3-3.xx&_nc_gid=MjqYFXS4EsUT7fF7gV3ocQ&_nc_ss=78289&oh=00_AQNeX4q0KidhNnAqjLmZVk25rM9Md0o126DMcN9etb7BEA&oe=6AC51880", "duration_seconds": null }, "author": { "username": null, "display_name": "Meta", "avatar_url": null, "verified": null }, "engagement": { "views": null, "likes": 2199, "comments": 435, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-30T16:09:30.000Z", "ext": { "author_id": "user_9cf871", "published_at_epoch": 1790784570, "reaction_counts": [ { "type": "like", "count": 1854 }, { "type": "love", "count": 257 } ], "feedback_id": "ZmVlZGJhY2s6MTE1MTY1NTI3NzUyMzY4MQ==" } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": null, "vs_creator": { "ratio": null, "metric": "likes", "reason": "too_young" } } } ], "next_cursor": "sc2.eyJzIjoiYiIsImMiOiJDZzhPYjNKbllXNXBZMTlqZFhKemIzSUpBQUFDbWtGUlNGUm9iWGMyTXkxR1MyazJiV0Z4TWtNdFJFOVpNbXRZU25SZmFHVkJVVjlhYUVnd2FVVm5aMDEyVmpCcldXYzBialpxWjBrMlFVaFFRV0ZvZVVoNmRUWlNaVlY1Ykc1Qk0yMUphR3BHUW1sMFdGQTBRMDl3TW1wemIxUXhRbWhuUTBwR1lXbG5kM0pzWHpneE0wNXRjVlJQY3pGNlFUWlZXRzVUUkV0V2FGcFljMmgyVVVremNEWm1RVWhIU0VWV1VtTk1iMVJCWVUxMlVHNXpiVVpEVkRCVFpqRjNUMWhmY0dWd2JGSXlUbkJhWm5acmFGUm5jekV6V0ZOM1NIY3paR1ZTWTBKNFpHRnRWbWRaVVZSbmJXbHZTWFU0WjAxa1VVdHVhMGh4UTBKdFlXeEtaazVqYjI5MmRrb3RlVTlZWTNKdWNqbFVVa0ZyTlhoWFpIcG1TSFJIYzBwM1l6WkJXVVpaYkRaTGEyTkdlbTFvTkhwUU5rNXZOSFI0U0cxbWNHMXFSRTl4UXpCeGVGcEpablJmYzBOS2VWTXhkMTkxUlY5U05Gb3plamgwUkZJNVpVNHdVa2xVYW1GWlNtMWpNR2N5TUc5R01GVXRja3hxVkdGa1J6ZGZSMmQyVWpCMFluSlhkMVpzTmxRMVJGWnlURTFEY0hKRVYybDJkV05NWTB0NFExRk9TbGwzWmt4ek5VWjVlSGhYUVhkSmEzbG5PWEZ0Tm5sNlJrbzNia0pLTlZkSWNsWjRNVWh6YUc1RlRUUkxRazA1WkhsVU4wdHRaV1pLTUZvMVJXdGZTMTl2UVhoR1prRkJWa3RTVDB0cVoyUmZkREZLU0c5YWMwd3daWGRoYldzeFpUUkVVRGR3YlRWSlVXSjJObGc0U0hJNWNISkRaMDFNYUVGWVUxcDVlalJUYUhGQlpFUm5TREphUkVKRVJrVm9UWGhaTmpGb1FtNWxXRkJ2U2tkclpEaDNkSHBKY1RoVFNHbHNUWGx0U1RSU05rRjBjSEJzV0VWUmRVTlZZV2g1WlVkQmVGcEhNREY2YmxFNFRraEZjbVZPY3pKV2FXTjRaRGxaV21oV01TMTZjamMwVGxSSU5rWTJaV053VjNCSmJuSXhNelJtYzNSb05XVkdaelF5WjBOVGRGRXpWbW94WmxOQ2RFdEhWRmcyWnc4SllXUmZZM1Z5YzI5eURnOFBaMnh2WW1Gc1gzQnZjMmwwYVc5dUFnQVBCbTltWm5ObGRBSUFEeEJzWVhOMFgyRmtYM0J2YzJsMGFXOXVBdjhCIn0", "total": null, "creator_baseline": { "baseline": null, "reason": "fewer_than_eight", "rows_used": 1, "cadence": "measured" }, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWWlJc0ltTWlPaUpEWnpoUFlqTktibGxYTlhCWk1UbHFaRmhLZW1JelNVcEJRVUZEYld0R1VsTkdVbTlpV0dNeVRYa3hSMU15YXpKaVYwWjRUV3ROZEZKRk9WcE5iWFJaVTI1U1ptRkhWa0pWVmpsaFlVVm5kMkZWVm01YU1ERXlWbXBDY2xkWFl6QmlhbHB4V2pCck1sRlZhRkZSVjBadlpWVm9ObVJVV2xOYVZsWTFZa2MxUWsweU1VcGhSM0JIVVcxc01GZEdRVEJSTURsM1RXMXdlbUl4VVhoUmJXaHVVVEJ3UjFsWGJHNWtNMHB6V0hwbmVFMHdOWFJqVmxKUVkzcEdObEZVV2xaWFJ6VlVVa1YwVjJGR2NGbGpNbWd5VlZWcmVtTkVXbTFSVldoSVUwVldWMVZ0VGsxaU1WSkNXVlV4TWxWSE5YcGlWVnBFVmtSQ1ZGcHFSak5VTVdobVkwZFdkMkpHU1hsVWJrSmhXbTVhY21GR1VtNWpla1Y2VjBaT00xTklZM3BhUjFaVFdUQktORnBIUm5SV2JXUmFWVlpTYm1KWGJIWlRXRlUwV2pBeGExVlZkSFZoTUdoNFVUQktkRmxYZUV0YWF6VnFZakk1TW1ScmIzUmxWVGxaV1ROS2RXTnFiRlZWYTBaeVRsaG9XRnBJY0cxVFNGSklZekJ3TTFsNldrSlhWVnBhWWtSYVRHRXlUa2RsYlRGdlRraHdVVTVyTlhaT1NGSTBVMGN4YldOSE1YRlNSVGw0VVhwQ2VHVkdjRXBhYmxKbVl6Qk9TMlZXVFhoa01Ua3hVbFk1VTA1R2IzcGxhbWd3VWtaSk5WcFZOSGRWYTJ4VllXMUdXbE50TVdwTlIyTjVUVWM1UjAxR1ZYUmphM2h4VmtkR2ExSjZaR1pTTW1ReVZXcENNRmx1U2xoa01WcHpUbXhSTVZKR1dubFVSVEZFWTBoS1JWWXliREprVjA1TldUQjBORkV4Ums5VGJHd3pXbXQ0ZWs1VldqVmxTR2hZVVZoa1NtRXpiRzVQV0VaMFRtNXNObEpyYnpOaWEwcExUbFprU1dOc1dqUk5WV2g2WVVjMVJsUlVVa3hSYXpBMVdraHNWVTR3ZEhSYVYxcExUVVp2TVZKWGRHWlRNVGwyVVZob1IxcHJSa0pXYTNSVFZEQjBjVm95VW1aa1JFWkxVMGM1WVdNd2QzZGFXR1JvWWxkemVGcFVVa1ZWUkdSM1lsUldTbFZYU2pKT2JHYzBVMGhKTldOSVNrUmFNREZOWVVWR1dWVXhjRFZsYWxKVVlVaEdRbHBGVW01VFJFcGhVa1ZLUlZKclZtOVVXR2hhVG1wR2IxRnROV3hYUmtKMlUydGtjbHBFYUROa1NIQktZMVJvVkZOSGJITlVXR3gwVTFSU1UwNXJSakJqU0VKelYwVldVbVJWVGxaWlYyZzFXbFZrUW1WR2NFaE5SRVkyWW14Rk5GUnJhRVpqYlZaUFkzcEtWMkZYVGpSYVJHeGFWMjFvVjAxVE1UWmphbU13Vkd4U1NVNXJXVEphVjA1M1ZqTkNTbUp1U1hoTmVsSnRZek5TYjA1WFZrZGFlbEY1V2pCT1ZHUkdSWHBXYlc5NFdteE9RMlJGZEVoV1JtY3lXbmM0U2xsWFVtWlpNMVo1WXpJNWVVUm5PRkJhTW5oMldXMUdjMWd6UW5aak1td3dZVmM1ZFVGblFWQkNiVGx0V201T2JHUkJTVUZFZUVKeldWaE9NRmd5Um10WU0wSjJZekpzTUdGWE9YVkJkamhDSW4wIiwiZSI6ImZhY2Vib29rL3Byb2ZpbGUvcG9zdHMiLCJwIjoiY3Vyc29yIn0", "has_more": true, "page_size": 3, "stopped_at": null }, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/post": { "get": { "summary": "Get Facebook post details", "description": "Returns detailed information about a specific Facebook post: the post text, like count, comment count, share count, media attachments, author info, and the per-reaction breakdown on `post.ext.reaction_counts` (`[{type, count}]`, highest first, zero-count reactions omitted: `like`, `love`, `care`, `haha`, `wow`, `sad`, `anger`). `post.ext.media_type` is `video` for a reel or a video, `image` for a single photo, `carousel` for an album, and null for a text-only or link-share post. `post.content.duration_seconds` is a video's length when Facebook sends one. It is null on a photo and can also be null on an older `/videos/` post, so use `post.ext.media_type` to tell a video from a photo. Only a video can have a transcript. `/v1/facebook/post/transcript` returns 404 `no_captions` at 0 credits on a photo or text post, and also on a video with no speech. `post.ext.feedback_id` is the join key `/v1/facebook/post/comments` accepts, so you can chain post to comments off a single lookup instead of paying for the URL resolution twice. A post published in a Facebook group also carries the group on `post.ext.group`: `id` is the group's key as its link spells it (the numeric id, or the vanity name a group set), and `url` is the canonical `https://www.facebook.com/groups//` form that `/v1/facebook/group` and `/v1/facebook/group/posts` take. Both are read from the post's link, so they come at no extra cost on every group post, whichever link form you send (`/permalink/`, `/posts/`, `?story_fbid=`, or the `m.` and `web.` hosts). `post.ext.group.name` and `post.ext.group.members` are null unless you send `include=group`, which looks the group up in the same call and fills its name and member count for 1 extra credit; the credit is kept only when the group's name comes back. A post that is not in a group has no `post.ext.group` and is never charged for the lookup.", "tags": [ "facebook" ], "operationId": "get_facebook_post", "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 post. include=group holds 1 more and keeps it only when the group's name comes back, so a call with include=group is at most 2 credits; it is refunded when the post is not in a group, when the lookup fails, and when the group was looked up recently and is served from cache.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full URL of the Facebook post, reel or video. A share link from Facebook's Copy link (`https://www.facebook.com/share/v/…`, `/share/p/…`, `/share/r/…` or `/share/…`) is accepted and resolved to the post it names.", "schema": { "type": "string" }, "example": "https://www.facebook.com/OGCCopperfields/posts/pfbid02mAPifrgyzhGeAAhMGyNU4J2dFdFpAtTfb6p22yCQMHpzwqK9zh9XHS8Bm39tk7mwl" }, { "name": "get_comments", "in": "query", "required": false, "description": "Accepted for backwards compatibility and currently a NO-OP: this endpoint returns the same body with or without it. Use `/v1/facebook/post/comments` (1 credit) for comments, passing the `post.ext.feedback_id` this response returns.", "schema": { "type": "boolean" } }, { "name": "get_transcript", "in": "query", "required": false, "description": "Accepted for backwards compatibility and currently a NO-OP: this endpoint returns the same body with or without it. Use `/v1/facebook/post/transcript` for a video transcript.", "schema": { "type": "boolean" } }, { "name": "include", "in": "query", "required": false, "description": "Set to `group` (one token only) to fill `post.ext.group.name` and `post.ext.group.members` (the member count) on a post published in a Facebook group, in this one call. It costs 1 extra credit, kept only when the group's name comes back: a post that is not in a group, a lookup that fails and a group already in cache are refunded, so the call is never more than 2 credits. The lookup adds about 3 to 7 seconds when it runs, never more than 12, and nothing when the group is cached; read `data.hydration` for the credits held and kept and the time. The group's `id` and `url` are on every group post without it.", "schema": { "type": "string", "enum": [ "group" ] } }, { "name": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 600 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 3600 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/post" }, "data": { "type": "object", "description": "Platform-specific response data", "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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "number", "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": [ "number", "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": [ "number", "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", "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "number", "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; discover reads a country from it into `geo.country` (`source: author_location`). 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": [ "number", "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" }, "link_domain": { "type": [ "string", "null" ], "description": "String at post.ext.link_domain" }, "upvote_ratio": { "type": [ "number", "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" ], "enum": [ "video", "short", "live", "channel", "playlist", 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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "enum": [ "image", "video", "carousel", 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": [ "number", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": { "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": { "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": [ "object", "null" ], "description": "Object 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": { "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/profile/posts`, `/v1/instagram/profile/reels`, `/v1/instagram/search/reels`, `/v1/tiktok/profile/videos` 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": [ "object", "null" ], "description": "Object 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", "enum": [ "image", "video" ], "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "number", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "number", "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": [ "number", "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": [ "object", "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": [ "object", "null" ], "description": "Object at post.ext.retweeted_post" }, "quote_count": { "type": [ "number", "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": { "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": [ "object", "null" ], "description": "Object 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": "object", "description": "Object 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": [ "number", "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": [ "object", "null" ], "description": "Object at post.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: post.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.description" } } } }, "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" ], "enum": [ "minute", "hour", "day", "week", "month", "year", 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": [ "number", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "number", "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": [ "object", "null" ], "description": "Object 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": [ "number", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "object", "null" ], "description": "Object at post.ext.dsp_ids", "additionalProperties": { "type": "string", "description": "String 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": "object", "description": "Object at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "object", "description": "Object at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "object", "description": "Object 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": [ "object", "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": [ "object", "null" ], "description": "Object 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": [ "number", "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": "number", "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": [ "object", "null" ], "description": "Object at post.ext.event" }, "trend": { "type": [ "object", "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" }, "numeric_id": { "type": [ "number", "null" ], "description": "Numeric at post.ext.numeric_id" }, "outbound_url": { "type": [ "string", "null" ], "description": "String at post.ext.outbound_url" }, "group": { "type": [ "object", "null" ], "description": "Object at post.ext.group" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "number", "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": [ "number", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "number", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "number", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "enum": [ "target", "other_named_thing", "generic_word", "not_present" ], "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "number", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "number", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "string", "boolean", "null" ], "description": "Union: number | string | boolean" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } } } }, "hydration": { "type": "object", "description": "Present when the request asked for a row join with `include=`, or sent a param that implies one. What the join did and what it cost. On a multi-page walk it sums every page. A join that always runs for free is left out.", "properties": { "include": { "type": "string", "description": "The token that switched the join on.", "example": "profile" }, "implied_by": { "type": "string", "description": "Present when you did not send `include` and another param switched the join on. The join's credits (`extra_credits`) are then part of `credits_used`. Absent when you sent `include` yourself." }, "rows": { "type": "integer", "description": "Rows on the page after any row cap.", "example": 20 }, "looked_up": { "type": "integer", "description": "Rows that needed a lookup (at least one field the join fills was empty).", "example": 20 }, "filled": { "type": "integer", "description": "Rows where at least one field was filled by the join.", "example": 18 }, "cached": { "type": "integer", "description": "Of `filled`, rows filled from the sibling endpoint's cache at no charge.", "example": 0 }, "unfilled": { "type": "integer", "description": "Rows that needed a lookup and were not filled (the lookup failed, was skipped, or had nothing to copy). Their credits are refunded.", "example": 2 }, "credits_held": { "type": "integer", "description": "Credits held up front for the join, on top of the page's own price.", "example": 20 }, "extra_credits": { "type": "integer", "description": "Of `credits_held`, the credits kept: one lookup's price for each distinct key filled from a fresh lookup. The rest was refunded.", "example": 18 }, "ms": { "type": "integer", "description": "Time the join added, in milliseconds.", "example": 2400 }, "cached_page": { "type": "boolean", "description": "True when the whole page was served from cache, so the join cost nothing on this call.", "example": true }, "batches": { "type": "integer", "description": "Joins that look rows up in batches only: how many batch calls were made. Absent on a join that looks rows up one by one." }, "from_earlier_pages": { "type": "integer", "description": "`max_pages`, `max_items` and `max_credits` walks only: rows filled free from a key already looked up on an earlier page of the same walk. Not counted in `looked_up`, `filled` or `cached`. Absent when zero." }, "steps": { "type": "array", "description": "Present when the request asked for more than one join (`include=engagement,channel`): one report per join, in the order they ran. The top-level numbers are then the page's: rows looked up or filled by any join, and the credits and time of all of them together.", "items": { "type": "object", "description": "One join's report.", "properties": { "include": { "type": "string", "description": "The token that switched the join on.", "example": "profile" }, "implied_by": { "type": "string", "description": "Present when you did not send `include` and another param switched the join on. The join's credits (`extra_credits`) are then part of `credits_used`. Absent when you sent `include` yourself." }, "rows": { "type": "integer", "description": "Rows on the page after any row cap.", "example": 20 }, "looked_up": { "type": "integer", "description": "Rows that needed a lookup (at least one field the join fills was empty).", "example": 20 }, "filled": { "type": "integer", "description": "Rows where at least one field was filled by the join.", "example": 18 }, "cached": { "type": "integer", "description": "Of `filled`, rows filled from the sibling endpoint's cache at no charge.", "example": 0 }, "unfilled": { "type": "integer", "description": "Rows that needed a lookup and were not filled (the lookup failed, was skipped, or had nothing to copy). Their credits are refunded.", "example": 2 }, "credits_held": { "type": "integer", "description": "Credits held up front for the join, on top of the page's own price.", "example": 20 }, "extra_credits": { "type": "integer", "description": "Of `credits_held`, the credits kept: one lookup's price for each distinct key filled from a fresh lookup. The rest was refunded.", "example": 18 }, "ms": { "type": "integer", "description": "Time the join added, in milliseconds.", "example": 2400 }, "cached_page": { "type": "boolean", "description": "True when the whole page was served from cache, so the join cost nothing on this call.", "example": true }, "batches": { "type": "integer", "description": "Joins that look rows up in batches only: how many batch calls were made. Absent on a join that looks rows up one by one." }, "from_earlier_pages": { "type": "integer", "description": "`max_pages`, `max_items` and `max_credits` walks only: rows filled free from a key already looked up on an earlier page of the same walk. Not counted in `looked_up`, `filled` or `cached`. Absent when zero." } } } } } }, "_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": [ "post" ] }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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 } } } }, "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" } } } } } } }, "/facebook/post/comments": { "get": { "summary": "List Facebook post comments", "description": "Returns a list of comments on a specific Facebook post. Each comment includes the author name, comment text, like count, reply count, and creation timestamp.", "tags": [ "facebook" ], "operationId": "get_facebook_post_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.", "x-socialcrawl-oneOf": [ [ "url", "feedback_id" ] ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "Full URL of the Facebook post to fetch comments for. Share links (`/share/v/…`, `/share/p/…`, `/share/r/…`, `/share/…`) are accepted. (one of: url, feedback_id; at least one required)", "schema": { "type": "string" }, "example": "https://www.facebook.com/Meta/videos/a-slightly-life-changing-story/1459847961114516/" }, { "name": "feedback_id", "in": "query", "required": false, "description": "Using feedback_id (instead of url) will *really* speed up the request. You can get the feedback_id when you make a request to /v1/facebook/post. (one of: url, feedback_id; at least one required)", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor to get more comments. Get 'cursor' from previous response.", "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 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": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 300 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 300 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/post/comments" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical comment wrappers ({ comment, computed })", "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": [ "number", "null" ], "description": "Like / upvote count" }, "replies": { "type": [ "number", "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", "number", "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": [ "number", "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": [ "number", "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": { "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": { "description": "Leaf at comment.ext.preview_replies" } }, "lookup": { "type": [ "object", "null" ], "description": "Object 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": [ "number", "null" ], "description": "Numeric at comment.ext.subreddit_subscribers" }, "post_score": { "type": [ "number", "null" ], "description": "Numeric at comment.ext.post_score" }, "post_comment_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "The commenter's following count as embedded in this row. Same snapshot caveat as `author_followers`." }, "author_posts_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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`." } } } }, "computed": { "type": "object", "description": "Server-computed fields for this comment", "properties": { "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the comment text, or the platform's own label when it publishes one. Null when undetectable." }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "null" ], "description": "Numeric at computed.labels.*.*" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } } } } } } }, "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." }, "labels": { "type": "object", "description": "Present when the page's rows were put through labelling: the default labels on a list that carries them, and any labels you named with `label=`. Absent with `judgments=off`. Reports what was judged, what is still pending and what it cost.", "properties": { "presets": { "type": "array", "description": "The labels this report covers.", "items": { "type": "string", "description": "A label name.", "example": "sentiment" } }, "rows": { "type": "integer", "description": "Rows on the page before any drop.", "example": 50 }, "labelled": { "type": "integer", "description": "Rows that carry every label this report covers, freshly judged or from the shared store.", "example": 50 }, "cached": { "type": "integer", "description": "Of `labelled`, rows served entirely from the shared per-row label store.", "example": 0 }, "skipped": { "type": "integer", "description": "Deleted or empty rows. They are never sent for judging or billed and carry `labels: null`.", "example": 0 }, "unjudged": { "type": "integer", "description": "Rows that could not be judged this time (a failure, or past the number of rows one call judges). They carry `labels: null` and are never billed.", "example": 0 }, "dropped": { "type": "integer", "description": "Rows removed by an `exclude=` you asked for. Default labels never drop a row.", "example": 0 }, "dropped_ids": { "type": "array", "description": "Ids of the rows counted in `dropped`.", "items": { "type": "string", "description": "A row id." } }, "extra_credits": { "type": "integer", "description": "Credits the labels added to this call. Always 0 for the default labels.", "example": 0 }, "methodology_version": { "type": "string", "description": "The version of the label questions, so you can tell when they change.", "example": "labels/1" }, "mode": { "type": "string", "enum": [ "default", "requested" ], "description": "`default` when you sent no `label=` and the free default labels ran, `requested` when you named labels.", "example": "default" }, "status": { "type": "string", "enum": [ "complete", "partial", "skipped" ], "description": "`complete`: every judgeable row carries its labels. `partial`: some rows carry `labels: null`, still being judged (see `pending`) or not judged this time. `skipped`: default judging was switched off for this request by a capacity guard, and the page is exactly as it was before labels existed.", "example": "complete" }, "pending": { "type": "integer", "description": "Default labels only: rows still being judged when the page was sent. They ship with `labels: null`, keep being judged afterwards, and your next call for the same page carries them.", "example": 0 }, "pending_ids": { "type": "array", "description": "Ids of the rows counted in `pending`.", "items": { "type": "string", "description": "A row id." } }, "cached_page": { "type": "boolean", "description": "Present and true when the whole page came from the response cache, so this call judged nothing and charged nothing.", "example": true }, "default": { "type": "object", "description": "Present when you named some labels with `label=`: the report of the default labels you did not name, with its own `mode`, `status`, `pending` and `pending_ids`. Absent when you named every default.", "properties": { "presets": { "type": "array", "description": "The labels this report covers.", "items": { "type": "string", "description": "A label name.", "example": "sentiment" } }, "rows": { "type": "integer", "description": "Rows on the page before any drop.", "example": 50 }, "labelled": { "type": "integer", "description": "Rows that carry every label this report covers, freshly judged or from the shared store.", "example": 50 }, "cached": { "type": "integer", "description": "Of `labelled`, rows served entirely from the shared per-row label store.", "example": 0 }, "skipped": { "type": "integer", "description": "Deleted or empty rows. They are never sent for judging or billed and carry `labels: null`.", "example": 0 }, "unjudged": { "type": "integer", "description": "Rows that could not be judged this time (a failure, or past the number of rows one call judges). They carry `labels: null` and are never billed.", "example": 0 }, "dropped": { "type": "integer", "description": "Rows removed by an `exclude=` you asked for. Default labels never drop a row.", "example": 0 }, "dropped_ids": { "type": "array", "description": "Ids of the rows counted in `dropped`.", "items": { "type": "string", "description": "A row id." } }, "extra_credits": { "type": "integer", "description": "Credits the labels added to this call. Always 0 for the default labels.", "example": 0 }, "methodology_version": { "type": "string", "description": "The version of the label questions, so you can tell when they change.", "example": "labels/1" }, "mode": { "type": "string", "enum": [ "default", "requested" ], "description": "`default` when you sent no `label=` and the free default labels ran, `requested` when you named labels.", "example": "default" }, "status": { "type": "string", "enum": [ "complete", "partial", "skipped" ], "description": "`complete`: every judgeable row carries its labels. `partial`: some rows carry `labels: null`, still being judged (see `pending`) or not judged this time. `skipped`: default judging was switched off for this request by a capacity guard, and the page is exactly as it was before labels existed.", "example": "complete" }, "pending": { "type": "integer", "description": "Default labels only: rows still being judged when the page was sent. They ship with `labels: null`, keep being judged afterwards, and your next call for the same page carries them.", "example": 0 }, "pending_ids": { "type": "array", "description": "Ids of the rows counted in `pending`.", "items": { "type": "string", "description": "A row id." } }, "cached_page": { "type": "boolean", "description": "Present and true when the whole page came from the response cache, so this call judged nothing and charged nothing.", "example": true } } } } }, "label_share": { "type": "object", "description": "Present on a comment list that carries labels. What share of the page's comments are questions, show purchase intent, complain, or are positive, neutral or negative, each with a 90% confidence interval and up to three verbatim receipts. Counted from the labels already on the page's rows; nothing is dropped or reordered, and it costs nothing.", "properties": { "policy_version": { "type": "string", "description": "The version of the cuts used.", "example": "share/1" }, "presets": { "type": "object", "description": "One share per label.", "properties": { "question": { "type": "object", "description": "One label's share of the page, with the evidence behind it.", "properties": { "n": { "type": "integer", "description": "Rows considered.", "example": 50 }, "counted": { "type": "integer", "description": "Rows that counted toward the share.", "example": 12 }, "abstained": { "type": "integer", "description": "Rows left out of the share because the judgment was too uncertain or could not be made. They still count in `n`.", "example": 4 }, "share": { "type": [ "number", "null" ], "description": "`counted` divided by the rows that were decided (`n` minus `abstained`), from 0 to 1. Null when `too_few` is true, because the interval is too wide to publish a headline number.", "example": 0.26 }, "low": { "type": [ "number", "null" ], "description": "Lower end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.16 }, "high": { "type": [ "number", "null" ], "description": "Upper end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.39 }, "receipts": { "type": "array", "description": "Up to three rows that counted, with their text copied unchanged.", "items": { "type": "object", "description": "One verbatim receipt: a row that counted toward the share.", "properties": { "id": { "type": "string", "description": "The row's id." }, "text": { "type": "string", "description": "The row's text, copied unchanged." } } } }, "policy_version": { "type": "string", "description": "The version of the rules that set the cut, so you can tell when they change.", "example": "share/1" }, "too_few": { "type": "boolean", "description": "True when there are too few decided rows for the interval to be narrow enough to publish `share`.", "example": false }, "at_cut": { "type": "integer", "description": "Rows whose probability is at or above the documented 0.5 cut, weak yeses included.", "example": 14 }, "nulls": { "type": "integer", "description": "Rows that carry no value for this label (not judged, or deleted).", "example": 0 }, "low_confidence": { "type": "integer", "description": "Rows whose answer sat too close to the cut to count toward the share.", "example": 3 } } }, "purchase_intent": { "type": "object", "description": "One label's share of the page, with the evidence behind it.", "properties": { "n": { "type": "integer", "description": "Rows considered.", "example": 50 }, "counted": { "type": "integer", "description": "Rows that counted toward the share.", "example": 12 }, "abstained": { "type": "integer", "description": "Rows left out of the share because the judgment was too uncertain or could not be made. They still count in `n`.", "example": 4 }, "share": { "type": [ "number", "null" ], "description": "`counted` divided by the rows that were decided (`n` minus `abstained`), from 0 to 1. Null when `too_few` is true, because the interval is too wide to publish a headline number.", "example": 0.26 }, "low": { "type": [ "number", "null" ], "description": "Lower end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.16 }, "high": { "type": [ "number", "null" ], "description": "Upper end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.39 }, "receipts": { "type": "array", "description": "Up to three rows that counted, with their text copied unchanged.", "items": { "type": "object", "description": "One verbatim receipt: a row that counted toward the share.", "properties": { "id": { "type": "string", "description": "The row's id." }, "text": { "type": "string", "description": "The row's text, copied unchanged." } } } }, "policy_version": { "type": "string", "description": "The version of the rules that set the cut, so you can tell when they change.", "example": "share/1" }, "too_few": { "type": "boolean", "description": "True when there are too few decided rows for the interval to be narrow enough to publish `share`.", "example": false }, "at_cut": { "type": "integer", "description": "Rows whose probability is at or above the documented 0.5 cut, weak yeses included.", "example": 14 }, "nulls": { "type": "integer", "description": "Rows that carry no value for this label (not judged, or deleted).", "example": 0 }, "low_confidence": { "type": "integer", "description": "Rows whose answer sat too close to the cut to count toward the share.", "example": 3 } } }, "complaint": { "type": "object", "description": "One label's share of the page, with the evidence behind it.", "properties": { "n": { "type": "integer", "description": "Rows considered.", "example": 50 }, "counted": { "type": "integer", "description": "Rows that counted toward the share.", "example": 12 }, "abstained": { "type": "integer", "description": "Rows left out of the share because the judgment was too uncertain or could not be made. They still count in `n`.", "example": 4 }, "share": { "type": [ "number", "null" ], "description": "`counted` divided by the rows that were decided (`n` minus `abstained`), from 0 to 1. Null when `too_few` is true, because the interval is too wide to publish a headline number.", "example": 0.26 }, "low": { "type": [ "number", "null" ], "description": "Lower end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.16 }, "high": { "type": [ "number", "null" ], "description": "Upper end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.39 }, "receipts": { "type": "array", "description": "Up to three rows that counted, with their text copied unchanged.", "items": { "type": "object", "description": "One verbatim receipt: a row that counted toward the share.", "properties": { "id": { "type": "string", "description": "The row's id." }, "text": { "type": "string", "description": "The row's text, copied unchanged." } } } }, "policy_version": { "type": "string", "description": "The version of the rules that set the cut, so you can tell when they change.", "example": "share/1" }, "too_few": { "type": "boolean", "description": "True when there are too few decided rows for the interval to be narrow enough to publish `share`.", "example": false }, "at_cut": { "type": "integer", "description": "Rows whose probability is at or above the documented 0.5 cut, weak yeses included.", "example": 14 }, "nulls": { "type": "integer", "description": "Rows that carry no value for this label (not judged, or deleted).", "example": 0 }, "low_confidence": { "type": "integer", "description": "Rows whose answer sat too close to the cut to count toward the share.", "example": 3 } } }, "sentiment": { "type": "object", "description": "Sentiment, split into three bands.", "properties": { "positive": { "type": "object", "description": "One label's share of the page, with the evidence behind it.", "properties": { "n": { "type": "integer", "description": "Rows considered.", "example": 50 }, "counted": { "type": "integer", "description": "Rows that counted toward the share.", "example": 12 }, "abstained": { "type": "integer", "description": "Rows left out of the share because the judgment was too uncertain or could not be made. They still count in `n`.", "example": 4 }, "share": { "type": [ "number", "null" ], "description": "`counted` divided by the rows that were decided (`n` minus `abstained`), from 0 to 1. Null when `too_few` is true, because the interval is too wide to publish a headline number.", "example": 0.26 }, "low": { "type": [ "number", "null" ], "description": "Lower end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.16 }, "high": { "type": [ "number", "null" ], "description": "Upper end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.39 }, "receipts": { "type": "array", "description": "Up to three rows that counted, with their text copied unchanged.", "items": { "type": "object", "description": "One verbatim receipt: a row that counted toward the share.", "properties": { "id": { "type": "string", "description": "The row's id." }, "text": { "type": "string", "description": "The row's text, copied unchanged." } } } }, "policy_version": { "type": "string", "description": "The version of the rules that set the cut, so you can tell when they change.", "example": "share/1" }, "too_few": { "type": "boolean", "description": "True when there are too few decided rows for the interval to be narrow enough to publish `share`.", "example": false }, "at_cut": { "type": "integer", "description": "Rows whose probability is at or above the documented 0.5 cut, weak yeses included.", "example": 14 }, "nulls": { "type": "integer", "description": "Rows that carry no value for this label (not judged, or deleted).", "example": 0 }, "low_confidence": { "type": "integer", "description": "Rows whose answer sat too close to the cut to count toward the share.", "example": 3 } } }, "neutral": { "type": "object", "description": "One label's share of the page, with the evidence behind it.", "properties": { "n": { "type": "integer", "description": "Rows considered.", "example": 50 }, "counted": { "type": "integer", "description": "Rows that counted toward the share.", "example": 12 }, "abstained": { "type": "integer", "description": "Rows left out of the share because the judgment was too uncertain or could not be made. They still count in `n`.", "example": 4 }, "share": { "type": [ "number", "null" ], "description": "`counted` divided by the rows that were decided (`n` minus `abstained`), from 0 to 1. Null when `too_few` is true, because the interval is too wide to publish a headline number.", "example": 0.26 }, "low": { "type": [ "number", "null" ], "description": "Lower end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.16 }, "high": { "type": [ "number", "null" ], "description": "Upper end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.39 }, "receipts": { "type": "array", "description": "Up to three rows that counted, with their text copied unchanged.", "items": { "type": "object", "description": "One verbatim receipt: a row that counted toward the share.", "properties": { "id": { "type": "string", "description": "The row's id." }, "text": { "type": "string", "description": "The row's text, copied unchanged." } } } }, "policy_version": { "type": "string", "description": "The version of the rules that set the cut, so you can tell when they change.", "example": "share/1" }, "too_few": { "type": "boolean", "description": "True when there are too few decided rows for the interval to be narrow enough to publish `share`.", "example": false }, "at_cut": { "type": "integer", "description": "Rows whose probability is at or above the documented 0.5 cut, weak yeses included.", "example": 14 }, "nulls": { "type": "integer", "description": "Rows that carry no value for this label (not judged, or deleted).", "example": 0 }, "low_confidence": { "type": "integer", "description": "Rows whose answer sat too close to the cut to count toward the share.", "example": 3 } } }, "negative": { "type": "object", "description": "One label's share of the page, with the evidence behind it.", "properties": { "n": { "type": "integer", "description": "Rows considered.", "example": 50 }, "counted": { "type": "integer", "description": "Rows that counted toward the share.", "example": 12 }, "abstained": { "type": "integer", "description": "Rows left out of the share because the judgment was too uncertain or could not be made. They still count in `n`.", "example": 4 }, "share": { "type": [ "number", "null" ], "description": "`counted` divided by the rows that were decided (`n` minus `abstained`), from 0 to 1. Null when `too_few` is true, because the interval is too wide to publish a headline number.", "example": 0.26 }, "low": { "type": [ "number", "null" ], "description": "Lower end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.16 }, "high": { "type": [ "number", "null" ], "description": "Upper end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.39 }, "receipts": { "type": "array", "description": "Up to three rows that counted, with their text copied unchanged.", "items": { "type": "object", "description": "One verbatim receipt: a row that counted toward the share.", "properties": { "id": { "type": "string", "description": "The row's id." }, "text": { "type": "string", "description": "The row's text, copied unchanged." } } } }, "policy_version": { "type": "string", "description": "The version of the rules that set the cut, so you can tell when they change.", "example": "share/1" }, "too_few": { "type": "boolean", "description": "True when there are too few decided rows for the interval to be narrow enough to publish `share`.", "example": false }, "at_cut": { "type": "integer", "description": "Rows whose probability is at or above the documented 0.5 cut, weak yeses included.", "example": 14 }, "nulls": { "type": "integer", "description": "Rows that carry no value for this label (not judged, or deleted).", "example": 0 }, "low_confidence": { "type": "integer", "description": "Rows whose answer sat too close to the cut to count toward the share.", "example": 3 } } } } } } } } }, "comment_language": { "type": "object", "description": "Present on a comment list that carries labels. The mix of languages the page's commenters write in. It describes the comments, not a country.", "properties": { "policy_version": { "type": "string", "description": "The version of the cuts used.", "example": "share/1" }, "n": { "type": "integer", "description": "Comments considered.", "example": 50 }, "abstained": { "type": "integer", "description": "Comments left out because the language could not be told (emoji, a handle, a single word).", "example": 6 }, "judged_by": { "type": "object", "description": "How each comment's language was settled.", "properties": { "script": { "type": "integer", "description": "Comments settled from their writing system (Hangul, Kana, Thai and so on)." }, "detector": { "type": "integer", "description": "Comments settled from the row's own `computed.language`." }, "choice": { "type": "integer", "description": "Latin-script comments settled by a judged choice from a closed list of languages." } } }, "shares": { "type": "object", "description": "One share per language that was counted, keyed by language code (for example `en`, `ko`). Each value has `n`, `counted`, `abstained`, `share`, `low`, `high`, `receipts`, `policy_version` and `too_few`, as in `label_share`." } } }, "comment_recency": { "type": "object", "description": "Present on every comment list. How alive the thread is, from the comments on this page and the post's age. Rows are not dropped or reordered.", "properties": { "policy_version": { "type": "string", "description": "The version of the cuts used.", "example": "d09-1" }, "n": { "type": "integer", "description": "Comments considered, replies included.", "example": 50 }, "counted": { "type": "integer", "description": "Comments with a usable date.", "example": 50 }, "abstained": { "type": "integer", "description": "Comments with no usable date.", "example": 0 }, "share_last_24h": { "type": [ "number", "null" ], "description": "Share of dated comments written in the last 24 hours, from 0 to 1. A floor when `recent_share_is_floor` is true.", "example": 0.22 }, "share_later_half": { "type": [ "number", "null" ], "description": "Share of dated comments written in the later half of the post's life so far. Null when the post's date is unknown.", "example": 0.6 }, "too_few": { "type": "boolean", "description": "True when fewer than 8 comments are dated, so `stage` is `unknown`.", "example": false }, "stage": { "type": "string", "enum": [ "alive", "slowing", "spent", "too_young", "unknown" ], "description": "`alive`: comments are still arriving. `slowing`: fewer are arriving. `spent`: the thread has gone quiet. `too_young`: the post is under a day old. `unknown`: too few dated comments to say.", "example": "alive" }, "order": { "type": "string", "enum": [ "recent", "top", "default" ], "description": "The order this page was read in.", "example": "recent" }, "recent_share_is_floor": { "type": "boolean", "description": "True when the page was not read newest first, so newer comments may sit on a page you did not read and `share_last_24h` is at least this value.", "example": false }, "receipts": { "type": "array", "description": "Up to three of the newest comments from the last 24 hours, with their text copied unchanged.", "items": { "type": "object", "description": "One verbatim receipt: a row that counted toward the share.", "properties": { "id": { "type": "string", "description": "The row's id." }, "text": { "type": "string", "description": "The row's text, copied unchanged." } } } } } }, "walk": { "type": "object", "description": "Present when the request sent a row-walk param (`max_pages` above 1, `max_items`, `max_credits`, a row filter, `sort_rows` or `seen`). What the walk did across the pages it fetched. Each page is billed as one call, and its charge is recorded under its own request id.", "properties": { "pages": { "type": "integer", "description": "Pages fetched.", "example": 3 }, "stopped": { "type": "string", "enum": [ "end", "max_pages", "max_items", "max_credits", "time_budget", "page_error" ], "description": "Why the walk stopped. `end`: the list ran out. `max_pages`, `max_items` or `max_credits`: the limit you set was reached. `time_budget`: the request's time budget ran low. `page_error`: a later page failed. Unless it is `end`, `pagination.next_cursor` continues from where the walk stopped.", "example": "max_pages" }, "rows_fetched": { "type": "integer", "description": "Rows read across every page, before any filter.", "example": 60 }, "rows_returned": { "type": "integer", "description": "Rows in `data.items`.", "example": 41 }, "discarded": { "type": "object", "description": "Present when you sent a row filter. Rows the filters removed, counted once each under the first filter they failed. A row a filter cannot verify (no view count, no date, no country) is discarded.", "properties": { "views_below_min": { "type": "integer", "description": "Rows with fewer views than `min_views`." }, "views_unknown": { "type": "integer", "description": "Rows with no view count, when `min_views` was sent." }, "older_than_max_age": { "type": "integer", "description": "Rows published before the `max_age_days` window." }, "date_unknown": { "type": "integer", "description": "Rows with no publish date, when `max_age_days` was sent." }, "country_not_included": { "type": "integer", "description": "Rows registered to a country that is not in `country`." }, "country_unknown": { "type": "integer", "description": "Rows with no country, when `country` was sent." }, "country_excluded": { "type": "integer", "description": "Rows registered to a country listed in `exclude_country`." } } }, "repeats": { "type": "integer", "description": "Present when you sent `seen`: rows removed because your account already received them under that id." }, "duplicates": { "type": "integer", "description": "Present when above zero: rows a later page repeated from an earlier page of the same walk, kept once." }, "credits": { "type": "object", "description": "What the pages cost.", "properties": { "pages": { "type": "integer", "description": "Credits charged for the pages walked, before refunds." }, "refunded": { "type": "integer", "description": "Credits refunded across the pages." } } }, "request_ids": { "type": "array", "description": "The request id of each page walked. Each is its own entry in `GET /v1/credits/transactions`.", "items": { "type": "string", "description": "A row id." } } } }, "estimate": { "type": "object", "description": "Present only on a dry run (`dry_run=1`). A dry run charges 0 credits, fetches nothing and returns `data.valid`, `data.normalized_params` and this `estimate` in place of the usual rows. An invalid request is the normal free 400 instead.", "properties": { "kind": { "type": "string", "description": "Always `estimate`.", "example": "estimate" }, "version": { "type": "integer", "description": "The version of this estimate shape.", "example": 1 }, "id": { "type": "string", "description": "The endpoint, as `platform/resource`." }, "method": { "type": "string", "description": "The HTTP method.", "example": "GET" }, "valid": { "type": "boolean", "description": "True when the request would pass every check made before billing.", "example": true }, "hold": { "type": "integer", "description": "Exactly what the router would deduct up front for this request." }, "expected_min": { "type": "integer", "description": "The least a successful call settles at." }, "expected_max": { "type": "integer", "description": "The most a call can settle at. Unused hold is refunded." }, "unit": { "type": "string", "description": "Always `credits`.", "example": "credits" }, "pricing": { "type": "string", "enum": [ "flat", "metered" ], "description": "`flat`: the same price every call. `metered`: the price depends on the work done, and unused hold is refunded.", "example": "flat" }, "formula": { "type": "string", "description": "How the price is worked out, in words." }, "levers": { "type": "array", "description": "Params that change the price, each with the hold for the same request with that one change.", "items": { "type": "object", "description": "One lever.", "properties": { "param": { "type": "string", "description": "The param to change." }, "hold": { "type": "integer", "description": "The hold for the same request with this one change." }, "effect": { "type": "string", "description": "What the change does." } } } }, "cached_likely": { "type": "boolean", "description": "Always false: a dry run does not read the cache.", "example": false }, "normalized_params": { "type": "object", "description": "The params the router prices, after its own normalisation." }, "notes": { "type": "array", "description": "Plain-English notes about this quote.", "items": { "type": "string", "description": "One note." } }, "warnings": { "type": "array", "description": "Notices about the quote, such as a page count that had to be assumed.", "items": { "type": "string", "description": "One notice." } }, "rows_expected": { "type": "integer", "description": "Judged lists only: the most rows one call judges on this endpoint." }, "rows_cached": { "type": "integer", "description": "Judged lists only: rows already judged and free. 0 on a dry run, which sees no rows." }, "label_credits_min": { "type": "integer", "description": "Judged lists only: the least the paid labels add. 0 on a dry run, which sees no rows." }, "label_credits_max": { "type": "integer", "description": "Judged lists only: the most the paid labels can add. 0 when you asked for no paid label." }, "base_credits": { "type": "integer", "description": "Judged lists only: the call's price without the label and relevance holds." } } }, "held_back": { "type": "object", "description": "Present when you sent `fit=goal` with a `goal` and at least one block of the page was not needed for it. The held rows (or fields) stay in place as stubs of `{ id, held: true }`; this block lists them.", "properties": { "ids": { "type": "array", "description": "Ids of the rows or fields that were held back.", "items": { "type": "string", "description": "A row id." } }, "recall": { "type": "string", "description": "A recall id for the full page, which re-reads it from cache at no extra charge.", "example": "fit_3f9a1c0b7d2e4a58" } } }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/post/comments", "data": { "items": [ { "comment": { "id": "Y29tbWVudDo1NjMwNjMzMjg1ODg1OTdfNTMyNTQ3NDgxNTk0OTk2", "url": null, "parent_id": null, "post_id": "563063328588597", "text": "Sample comment text (redacted).", "author": { "username": "user_add51c", "display_name": "user_3d0e68", "avatar_url": "https://example.com/avatars/user_f59eee.png", "verified": null }, "engagement": { "likes": 0, "replies": 3 }, "flags": { "pinned": null, "deleted": false }, "published_at": "2022-04-13T02:26:17.000Z", "ext": { "feedback_id": "ZmVlZGJhY2s6NTYzMDYzMzI4NTg4NTk3XzUzMjU0NzQ4MTU5NDk5Ng==", "expansion_token": "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).", "reaction_counts": null } }, "computed": { "language": null, "labels": { "sentiment": { "level": 3, "score_0_1": 0.77, "confidence": 0.94 }, "question": { "p": 0.02 }, "purchase_intent": { "p": 0.02 }, "complaint": { "p": 0.02 } } } }, { "comment": { "id": "Y29tbWVudDo1NjMwNjMzMjg1ODg1OTdfNTcwNjY2Nzk0NDk0OTE3", "url": null, "parent_id": null, "post_id": "563063328588597", "text": "Sample comment text (redacted).", "author": { "username": "user_c5097a", "display_name": "user_edb910", "avatar_url": "https://example.com/avatars/user_606f32.png", "verified": null }, "engagement": { "likes": 0, "replies": 1 }, "flags": { "pinned": null, "deleted": false }, "published_at": "2022-04-13T04:09:36.000Z", "ext": { "feedback_id": "ZmVlZGJhY2s6NTYzMDYzMzI4NTg4NTk3XzU3MDY2Njc5NDQ5NDkxNw==", "expansion_token": "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).", "reaction_counts": null } }, "computed": { "language": null, "labels": { "sentiment": { "level": 4, "score_0_1": 1, "confidence": 1 }, "question": { "p": 0.02 }, "purchase_intent": { "p": 0.02 }, "complaint": { "p": 0.02 } } } } ], "next_cursor": "sc2.eyJzIjoiYiIsImMiOiJNVG94Tnprd09UVTFOREEwT2dGX08xam9FMGVBZzNkSC1yRzM1NVYxb255ZDNFNnlyZVBoMllrRzdvZFItbUZ6V0pMbWtVYmgzZWIxYVBJV3B1VjBiMlF3UXJUSnRCSzdIaXp6TEh4WHVIbGlXSmg5NVEzX1NnNzNwcEpTYWhmOERKMU1OeURNWWtmMlFTYTdiakpzOFpJU3M5MzRXU0hLYWgwRjlaeVRPQVo5blFrLVVZdkZ4S1ZJeExnckloTVVUN05BMUIzTmtfWllvN09ka1pxV2NDT0d0Y2FpMC1SMlNqMFpoOXBMWXZKMndrVkRoMThWZE5hZHNMWVA2WWFtUTlhLVJwVGxPN1lWZnlwTXI0Y1loNnZoV0MzN2pXaGZTUnpjSmNqUWJTaVBfRWFtZ1hha0Z3aDR0bUFiS3lIekx0eGR5RVFXdEJzMEFxX2FIcHBIMWVIMldYNWNSRFdyam9FRFliX3p4TV9vNFB3M3RrbzZjT2lmUWRwRVBaSXAifQ", "total": null, "labels": { "presets": [ "sentiment", "question" ], "rows": 10, "labelled": 10, "cached": 10, "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": 10, "counted": 2, "abstained": 0, "share": null, "low": 0.0686, "high": 0.4592, "receipts": [ { "id": "Y29tbWVudDo1NjMwNjMzMjg1ODg1OTdfNTcwNjk2MzY3ODI1Mjkz", "text": "Sample comment text (redacted)." }, { "id": "Y29tbWVudDo1NjMwNjMzMjg1ODg1OTdfNTcyODE1MzMwOTQ2NzMw", "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted)." } ], "policy_version": "share/1", "too_few": true, "at_cut": 2, "nulls": 0, "low_confidence": 0 }, "purchase_intent": { "n": 10, "counted": 0, "abstained": 0, "share": 0, "low": 0, "high": 0.2129, "receipts": [], "policy_version": "share/1", "too_few": false, "at_cut": 0, "nulls": 0, "low_confidence": 0 }, "complaint": { "n": 10, "counted": 2, "abstained": 0, "share": null, "low": 0.0686, "high": 0.4592, "receipts": [ { "id": "Y29tbWVudDo1NjMwNjMzMjg1ODg1OTdfNTcyNDQ5OTM0MzE2NjAz", "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted)." }, { "id": "Y29tbWVudDo1NjMwNjMzMjg1ODg1OTdfNTcyODE1MzMwOTQ2NzMw", "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted)." } ], "policy_version": "share/1", "too_few": true, "at_cut": 2, "nulls": 0, "low_confidence": 0 }, "sentiment": { "positive": { "n": 10, "counted": 5, "abstained": 1, "share": null, "low": 0.3035, "high": 0.782, "receipts": [ { "id": "Y29tbWVudDo1NjMwNjMzMjg1ODg1OTdfNTMyNTQ3NDgxNTk0OTk2", "text": "Sample comment text (redacted)." }, { "id": "Y29tbWVudDo1NjMwNjMzMjg1ODg1OTdfNTcwNjY2Nzk0NDk0OTE3", "text": "Sample comment text (redacted)." } ], "policy_version": "share/1", "too_few": true, "at_cut": 5, "nulls": 0, "low_confidence": 1 }, "neutral": { "n": 10, "counted": 2, "abstained": 1, "share": null, "low": 0.0765, "high": 0.4964, "receipts": [ { "id": "Y29tbWVudDo1NjMwNjMzMjg1ODg1OTdfNTcwNjk2MzY3ODI1Mjkz", "text": "Sample comment text (redacted)." }, { "id": "Y29tbWVudDo1NjMwNjMzMjg1ODg1OTdfNTcyODE1MzMwOTQ2NzMw", "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted)." } ], "policy_version": "share/1", "too_few": true, "at_cut": 2, "nulls": 0, "low_confidence": 1 }, "negative": { "n": 10, "counted": 2, "abstained": 1, "share": null, "low": 0.0765, "high": 0.4964, "receipts": [ { "id": "Y29tbWVudDo1NjMwNjMzMjg1ODg1OTdfNTcxMjE0MDU0NDQwMTkx", "text": "Sample comment text (redacted)." }, { "id": "Y29tbWVudDo1NjMwNjMzMjg1ODg1OTdfNTcyNDQ5OTM0MzE2NjAz", "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted)." } ], "policy_version": "share/1", "too_few": true, "at_cut": 2, "nulls": 0, "low_confidence": 1 } } } }, "comment_language": { "policy_version": "share/1", "n": 10, "abstained": 0, "judged_by": { "script": 0, "choice": 10 }, "shares": { "en": { "n": 10, "counted": 10, "abstained": 0, "share": 1, "low": 0.7871, "high": 1, "receipts": [ { "id": "Y29tbWVudDo1NjMwNjMzMjg1ODg1OTdfNTMyNTQ3NDgxNTk0OTk2", "text": "Sample comment text (redacted)." }, { "id": "Y29tbWVudDo1NjMwNjMzMjg1ODg1OTdfNTcwNjY2Nzk0NDk0OTE3", "text": "Sample comment text (redacted)." } ], "policy_version": "share/1", "too_few": false } } }, "comment_recency": { "policy_version": "d09-1", "n": 10, "counted": 10, "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.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWWlJc0ltTWlPaUpOVkc5NFRucHJkMDlVVlRGT1JFRXdUMmRHWDA4eGFtOUZNR1ZCWnpOa1NDMXlSek0xTlZZeGIyNTVaRE5GTm5seVpWQm9NbGxyUnpkdlpGSXRiVVo2VjBwTWJXdFZZbWd6WldJeFlWQkpWM0IxVmpCaU1sRjNVWEpVU25SQ1N6ZElhWHA2VEVoNFdIVkliR2xYU21nNU5WRXpYMU5uTnpOd2NFcFRZV2htT0VSS01VMU9lVVJOV1d0bU1sRlRZVGRpYWtwek9GcEpVM001TXpSWFUwaExZV2d3UmpsYWVWUlBRVm81YmxGckxWVlpka1o0UzFaSmVFeG5ja2xvVFZWVU4wNUJNVUl6VG10ZldsbHZOMDlrYTFweFYyTkRUMGQwWTJGcE1DMVNNbE5xTUZwb09YQk1XWFpLTW5kclZrUm9NVGhXWkU1aFpITk1XVkEyV1dGdFVUbGhMVkp3Vkd4UE4xbFdabmx3VFhJMFkxbG9OblpvVjBNek4ycFhhR1pUVW5walNtTnFVV0pUYVZCZlJXRnRaMWhoYTBaM2FEUjBiVUZpUzNsSWVreDBlR1I1UlZGWGRFSnpNRUZ4WDJGSWNIQklNV1ZJTWxkWU5XTlNSRmR5YW05RlJGbGlYM3A0VFY5dk5GQjNNM1JyYnpaalQybG1VV1J3UlZCYVNYQWlmUSIsImUiOiJmYWNlYm9vay9wb3N0L2NvbW1lbnRzIiwicCI6ImN1cnNvciJ9", "has_more": true, "page_size": 10 }, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/group/posts": { "get": { "summary": "List Facebook group posts", "description": "Returns posts from a public Facebook group, newest first. Each post carries the post text, reaction count, comment count, the per-reaction breakdown on `post.ext.reaction_counts`, author name and id, the group permalink, the exact publish timestamp, and any attached image or video. `engagement.shares` is null here for the same reason it is on `profile/posts`: Facebook exposes a share count on the post permalink only. Facebook serves this feed in small slices (**3 to 4 posts per page**) so deeper history is a cursor walk rather than one large call: send the `pagination.next_cursor` from each response back as `cursor` and repeat until `pagination.has_more` is false. A 30-page walk on a public group returned 91 posts with no duplicates and a cursor still open, so depth is bounded by how many pages you are willing to buy (1 credit each) rather than by a hard cap. All four `sort_by` values paginate; use `sort_by=CHRONOLOGICAL` to stay current on a busy group, since the default and `TOP_POSTS` mix older high-engagement posts into the first pages.", "tags": [ "facebook" ], "operationId": "get_facebook_group_posts", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-socialcrawl-oneOf": [ [ "url", "group_id" ] ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "Full URL of the Facebook group (one of: url, group_id; at least one required)", "schema": { "type": "string" }, "example": "https://www.facebook.com/groups/2204685680" }, { "name": "group_id", "in": "query", "required": false, "description": "The ID of the group (one of: url, group_id; at least one required)", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "required": false, "description": "How to sort the posts. CHRONOLOGICAL_LISTINGS reads the group's listings feed and can stall on some groups (a group with no listings feed does not answer); use the default sort, or CHRONOLOGICAL for posts in date order.", "schema": { "type": "string", "enum": [ "TOP_POSTS", "RECENT_ACTIVITY", "CHRONOLOGICAL", "CHRONOLOGICAL_LISTINGS" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor to get the next page of posts. Take it from `pagination.next_cursor` on the previous response.", "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": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 600 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 3600 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/group/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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "number", "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": [ "number", "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": [ "number", "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", "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "number", "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; discover reads a country from it into `geo.country` (`source: author_location`). 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": [ "number", "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" }, "link_domain": { "type": [ "string", "null" ], "description": "String at post.ext.link_domain" }, "upvote_ratio": { "type": [ "number", "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" ], "enum": [ "video", "short", "live", "channel", "playlist", 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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "enum": [ "image", "video", "carousel", 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": [ "number", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": { "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": { "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": [ "object", "null" ], "description": "Object 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": { "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/profile/posts`, `/v1/instagram/profile/reels`, `/v1/instagram/search/reels`, `/v1/tiktok/profile/videos` 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": [ "object", "null" ], "description": "Object 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", "enum": [ "image", "video" ], "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "number", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "number", "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": [ "number", "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": [ "object", "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": [ "object", "null" ], "description": "Object at post.ext.retweeted_post" }, "quote_count": { "type": [ "number", "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": { "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": [ "object", "null" ], "description": "Object 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": "object", "description": "Object 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": [ "number", "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": [ "object", "null" ], "description": "Object at post.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: post.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.description" } } } }, "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" ], "enum": [ "minute", "hour", "day", "week", "month", "year", 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": [ "number", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "number", "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": [ "object", "null" ], "description": "Object 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": [ "number", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "object", "null" ], "description": "Object at post.ext.dsp_ids", "additionalProperties": { "type": "string", "description": "String 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": "object", "description": "Object at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "object", "description": "Object at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "object", "description": "Object 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": [ "object", "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": [ "object", "null" ], "description": "Object 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": [ "number", "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": "number", "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": [ "object", "null" ], "description": "Object at post.ext.event" }, "trend": { "type": [ "object", "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" }, "numeric_id": { "type": [ "number", "null" ], "description": "Numeric at post.ext.numeric_id" }, "outbound_url": { "type": [ "string", "null" ], "description": "String at post.ext.outbound_url" }, "group": { "type": [ "object", "null" ], "description": "Object at post.ext.group" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "number", "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": [ "number", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "number", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "number", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "enum": [ "target", "other_named_thing", "generic_word", "not_present" ], "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "number", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "number", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "string", "boolean", "null" ], "description": "Union: number | string | boolean" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } } } } } } }, "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." }, "walk": { "type": "object", "description": "Present when the request sent a row-walk param (`max_pages` above 1, `max_items`, `max_credits`, a row filter, `sort_rows` or `seen`). What the walk did across the pages it fetched. Each page is billed as one call, and its charge is recorded under its own request id.", "properties": { "pages": { "type": "integer", "description": "Pages fetched.", "example": 3 }, "stopped": { "type": "string", "enum": [ "end", "max_pages", "max_items", "max_credits", "time_budget", "page_error" ], "description": "Why the walk stopped. `end`: the list ran out. `max_pages`, `max_items` or `max_credits`: the limit you set was reached. `time_budget`: the request's time budget ran low. `page_error`: a later page failed. Unless it is `end`, `pagination.next_cursor` continues from where the walk stopped.", "example": "max_pages" }, "rows_fetched": { "type": "integer", "description": "Rows read across every page, before any filter.", "example": 60 }, "rows_returned": { "type": "integer", "description": "Rows in `data.items`.", "example": 41 }, "discarded": { "type": "object", "description": "Present when you sent a row filter. Rows the filters removed, counted once each under the first filter they failed. A row a filter cannot verify (no view count, no date, no country) is discarded.", "properties": { "views_below_min": { "type": "integer", "description": "Rows with fewer views than `min_views`." }, "views_unknown": { "type": "integer", "description": "Rows with no view count, when `min_views` was sent." }, "older_than_max_age": { "type": "integer", "description": "Rows published before the `max_age_days` window." }, "date_unknown": { "type": "integer", "description": "Rows with no publish date, when `max_age_days` was sent." }, "country_not_included": { "type": "integer", "description": "Rows registered to a country that is not in `country`." }, "country_unknown": { "type": "integer", "description": "Rows with no country, when `country` was sent." }, "country_excluded": { "type": "integer", "description": "Rows registered to a country listed in `exclude_country`." } } }, "repeats": { "type": "integer", "description": "Present when you sent `seen`: rows removed because your account already received them under that id." }, "duplicates": { "type": "integer", "description": "Present when above zero: rows a later page repeated from an earlier page of the same walk, kept once." }, "credits": { "type": "object", "description": "What the pages cost.", "properties": { "pages": { "type": "integer", "description": "Credits charged for the pages walked, before refunds." }, "refunded": { "type": "integer", "description": "Credits refunded across the pages." } } }, "request_ids": { "type": "array", "description": "The request id of each page walked. Each is its own entry in `GET /v1/credits/transactions`.", "items": { "type": "string", "description": "A row id." } } } }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/group/posts", "data": { "items": [ { "post": { "id": "10167423135175681", "url": "https://www.facebook.com/groups/2204685680/permalink/10167423135175681/", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://scontent-mia3-3.xx.fbcdn.net/v/t39.99422-6/828653125_1118910373808082_6365666008250416614_n.png?stp=dst-jpg_tt6&cstp=mx1080x1350&ctp=s1080x1350&_nc_cat=109&ccb=1-7&_nc_sid=aa7b47&_nc_ohc=KT1XcYjiC7cQ7kNvwF5p5Cr&_nc_oc=AdqflMv2sKioYWxnyrpTP2Dnf9wbz3hI_Id9Lde25Qri5aog6QFOHTcLiw-ig7ySFZc&_nc_zt=14&_nc_ht=scontent-mia3-3.xx&_nc_gid=TnQ92KpU2EQnFDnsXDBFTA&_nc_ss=78289&oh=00_AQPwhM-Ho52afbYjZxKmHB0naLhs62YA3j3cRgqTlrvYvg&oe=6AC51924", "thumbnail_url": null, "duration_seconds": null }, "author": { "username": null, "display_name": "user_c6ec8f", "avatar_url": null, "verified": null }, "engagement": { "views": null, "likes": 4, "comments": 3, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-27T16:47:57.000Z", "ext": { "author_id": "user_c8973c", "published_at_epoch": 1790527677, "reaction_counts": [ { "type": "like", "count": 3 }, { "type": "sad", "count": 1 } ], "feedback_id": "ZmVlZGJhY2s6MTAxNjc0MjMxMzUxNzU2ODE=" } }, "computed": { "engagement_rate": null, "language": null, "content_category": "other", "estimated_reach": null } }, { "post": { "id": "10167419814695681", "url": "https://www.facebook.com/groups/2204685680/permalink/10167419814695681/", "content": { "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "media_urls": "https://scontent-iad6-1.xx.fbcdn.net/v/t39.30808-6/825267100_10245731634444721_8658574703047824983_n.jpg?_nc_cat=100&ccb=1-7&_nc_sid=aa7b47&_nc_ohc=vk1nleXByjAQ7kNvwHx-eKu&_nc_oc=AdoVbnOpMEWs6Ys9e24vAof4t4n5g4pHRqTIKSH3GVixL2h14ogCMHs9xB8td1R8ETY&_nc_zt=23&_nc_ht=scontent-iad6-1.xx&_nc_gid=IXTbL45iSLaH7WlSTpOheg&_nc_ss=70289&oh=00_AQMq__kGqdnVf0ColrOJ10SzxOd6aR0Sl0m6h9nh5oAU8w&oe=6AC518FA", "thumbnail_url": null, "duration_seconds": null }, "author": { "username": "user_bd0c85", "display_name": "user_d7a1c4", "avatar_url": null, "verified": null }, "engagement": { "views": null, "likes": 3, "comments": 0, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-27T00:18:14.000Z", "ext": { "published_at_epoch": 1790468294, "reaction_counts": [ { "type": "like", "count": 3 } ], "feedback_id": "ZmVlZGJhY2s6MTAxNjc0MTk4MTQ2OTU2ODE=" } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": null } } ], "next_cursor": "AQHTNRo5OUqtQZ6zJb5xNNhTuV4pYbXjFEHOqwAKqGF55xkxwCXhjRsvhez13H1bxtI0JLxRiUP3EScMky26wxBxyg:eyIwIjoxNzkwOTI2MzI0LCIxIjo3NjgyLCIzIjoxLCI0IjoxLCI1IjoyLCI2IjotMSwiNyI6LTEsIjgiOi0xfQ==", "total": null, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiQVFIVE5SbzVPVXF0UVo2ekpiNXhOTmhUdVY0cFliWGpGRUhPcXdBS3FHRjU1eGt4d0NYaGpSc3ZoZXoxM0gxYnh0STBKTHhSaVVQM0VTY01reTI2d3hCeHlnOmV5SXdJam94Tnprd09USTJNekkwTENJeElqbzNOamd5TENJeklqb3hMQ0kwSWpveExDSTFJam95TENJMklqb3RNU3dpTnlJNkxURXNJamdpT2kweGZRPT0iLCJlIjoiZmFjZWJvb2svZ3JvdXAvcG9zdHMiLCJwIjoiY3Vyc29yIn0", "has_more": true, "page_size": 4 }, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/group": { "get": { "summary": "Get a Facebook group", "description": "Returns a Facebook group's public record: name, description, member count, privacy, visibility, and creation date. Pass the group URL or group_id. Use group/posts for the group's recent posts.", "tags": [ "facebook" ], "operationId": "get_facebook_group", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-socialcrawl-oneOf": [ [ "url", "group_id" ] ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "Full URL of the Facebook group. (one of: url, group_id; at least one required)", "schema": { "type": "string" }, "example": "https://www.facebook.com/groups/2204685680" }, { "name": "group_id", "in": "query", "required": false, "description": "Numeric Facebook group id. (one of: url, group_id; at least one required)", "schema": { "type": "string" } }, { "name": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 900 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 3600 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/group" }, "data": { "type": "object", "description": "Platform-specific response data", "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": [ "number", "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": [ "number", "null" ], "description": "Number of accounts followed" }, "posts_count": { "type": [ "number", "null" ], "description": "Total number of posts / videos / tracks / episodes" }, "likes_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at author.ext.employee_count_range.start" }, "end": { "type": [ "number", "null" ], "description": "Numeric at author.ext.employee_count_range.end" } } }, "founded_year": { "type": [ "number", "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": [ "object", "null" ], "description": "Object at author.ext.headquarters" }, "locations": { "type": [ "array", "null" ], "description": "Array at author.ext.locations", "items": { "description": "Leaf at author.ext.locations" } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at author.ext.hashtags", "items": { "description": "Leaf at author.ext.hashtags" } }, "funding": { "type": [ "object", "null" ], "description": "Object 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": [ "number", "null" ], "description": "Numeric at author.ext.rating_count" }, "talking_about_count": { "type": [ "number", "null" ], "description": "Numeric at author.ext.talking_about_count" }, "business_hours": { "type": [ "array", "null" ], "description": "Array at author.ext.business_hours", "items": { "description": "Leaf at author.ext.business_hours" } }, "links": { "type": [ "array", "null" ], "description": "Array at author.ext.links", "items": { "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" ], "enum": [ "app", "web", 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": [ "number", "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": [ "object", "null" ], "description": "Object 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": [ "object", "null" ], "description": "Object at author.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: author.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at author.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at author.ext.localizations.*.description" } } } }, "monthly_listeners": { "type": [ "number", "null" ], "description": "Numeric at author.ext.monthly_listeners" }, "total_ratings": { "type": [ "number", "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": [ "number", "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": "object", "description": "Object at author.ext.rules" } }, "weekly_active_users": { "type": [ "number", "null" ], "description": "Numeric at author.ext.weekly_active_users" }, "weekly_contributions": { "type": [ "number", "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": [ "number", "null" ], "description": "Numeric at author.ext.post_karma" }, "comment_karma": { "type": [ "number", "null" ], "description": "Numeric at author.ext.comment_karma" }, "awardee_karma": { "type": [ "number", "null" ], "description": "Numeric at author.ext.awardee_karma" }, "trophy_count": { "type": [ "number", "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": { "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": [ "object", "null" ], "description": "Object at author.ext.group" }, "search_hit": { "type": [ "object", "null" ], "description": "Nested object: author.ext.search_hit", "properties": { "match": { "type": [ "string", "null" ], "enum": [ "group_page", "post_in_group", "channel_page", "post_in_channel", 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": [ "number", "null" ], "description": "Numeric at author.ext.visitors_today" }, "visitors_total": { "type": [ "number", "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" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "number", "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": [ "number", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "number", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "number", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "enum": [ "target", "other_named_thing", "generic_word", "not_present" ], "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "number", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "number", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "string", "boolean", "null" ], "description": "Union: number | string | boolean" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } } } }, "_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": [ "author" ] }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/group", "data": { "author": { "id": "2204685680", "username": null, "display_name": "PHP", "avatar_url": null, "bio": "Welcome to the PHP group.\n\n🐘 PHP: Hypertext Preprocessor is a popular general-purpose scripting language that is especially suited to web development.\nhttps://php.net\n\n⚠️ GROUP RULES:\n- Be nice and respectful to others.\n- Post in English.\n- Be professional. Aim for good quality in questions and discussions.\n- For sharing code use nopaste sites.\n- Publish only PHP and web-centric development related topics.\n- Job offers have to be PHP or web development related.\n- Don't share personal data (emails, phone numbers...).\n- Read https://conduct.php.earth\n\n📌 GROUP GUIDES:\n- How to ask smart questions?\nhttps://php.earth/questions\n- How to answer questions?\nhttps://php.earth/answers\n- Frequently asked questions:\nhttps://docs.php.earth/faq\n- Where to start?\nhttps://docs.php.earth/faq/intro/what-is-php\n- PHP frameworks:\nhttps://docs.php.earth/misc/frameworks\n- Nopaste sites:\nhttps://docs.php.earth/interop/nopaste\n- Recommended PHP books:\nhttps://docs.php.earth/faq/intro/books\n\n📘 MUST CHECK:\n- Official PHP docs:\nhttps://php.net/docs\n- PHP best practices, coding standards, tutorials:\nhttps://phptherightway.com\n- Disproval of various PHP delusions and superstitions:\nhttps://phpdelusions.net\n- Open source PHP code:\nhttps://packagist.org\n\n🌍 LOCAL GROUPS:\nDiscuss PHP in your language or meet PHP people in person\nhttps://php.ug\n\n🤝 ADMINS:\n- Have questions or experiencing issues? Ask admins here:\nfb.com/groups/2204685680/permalink/10156916600625681", "verified": null, "followers": 255625, "following": null, "posts_count": null, "likes_count": null, "url": "https://www.facebook.com/groups/2204685680", "private": null, "joined_at": "2006-07-12", "ext": { "group": { "privacy_label": "Public", "privacy_description": "Anyone can see who's in the group and what they post.", "visibility_label": "Visible", "visibility_description": "Anyone can find this group.", "member_count_text": "255,625 total members", "administrator_count": 8, "moderator_count": 7, "history_summary": "Group created on July 12, 2006", "categories": [], "rules": [], "administrators": [ { "id": "user_9e7fd8", "name": "user_b22341", "url": "https://example.com/user_6adaf3", "profile_picture_url": "https://example.com/avatars/user_c51967.png" }, { "id": "user_0a1eff", "name": "user_a5ebf7", "url": "https://example.com/user_acffdb", "profile_picture_url": "https://example.com/avatars/user_4a7709.png" } ], "moderators": [ { "id": "user_1173e7", "name": "user_754177", "url": "https://example.com/user_33242d", "profile_picture_url": "https://example.com/avatars/user_4445a5.png" }, { "id": "user_42d373", "name": "user_b7b9dd", "url": "https://example.com/user_254f44", "profile_picture_url": "https://example.com/avatars/user_71a8cf.png" } ], "activity": { "posts_last_day": 0, "posts_last_month": 7, "new_members_text": "No new members in the last week" }, "about_info": [ { "type": "XFBPrivacyGroupsAboutInfoItem", "label": "Public", "description": "Anyone can see who's in the group and what they post." }, { "type": "XFBDiscoverabilityGroupsAboutInfoItem", "label": "Visible", "description": "Anyone can find this group." } ] } } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "tech", "estimated_reach": null } }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/post/transcript": { "get": { "summary": "Get Facebook video transcript", "description": "Returns the transcript of a Facebook video post. Videos up to 10 minutes (600 seconds) are supported; `post_id` is null on a video longer than 2 minutes. Every outcome below is deterministic for a given URL, so retrying returns the same answer, and none of them costs credits. A longer video returns 400 INVALID_REQUEST with `error.details.reason: video_too_long` and `max_seconds`. A video with no speech, or a post with no video, returns 404 RESOURCE_NOT_FOUND with `error.details.reason: no_captions`, because Facebook answers those two identically. A reel with only music or no sound has no speech, so this 404 is the expected answer for it. If you already have the post from `/v1/facebook/post`, check `post.ext.media_type` before calling. Only `video`, a reel or a video, can have a transcript. A photo, album or text post carries `image`, `carousel` or null and has nothing to transcribe. A video over 2 minutes is transcribed on demand and can take a minute or more, so allow up to 300 seconds before your HTTP client times out.", "tags": [ "facebook" ], "operationId": "get_facebook_post_transcript", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "premium", "x-credit-cost": 10, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full URL of the Facebook video post. Share links (`/share/v/…`, `/share/r/…`) are accepted.", "schema": { "type": "string" }, "example": "https://www.facebook.com/Meta/videos/a-slightly-life-changing-story/1459847961114516/" }, { "name": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 2592000 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 2592000 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/post/transcript" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "transcript": { "type": [ "string", "null" ], "description": "Full transcript text. Plain string for TikTok/Facebook/Twitter; see `transcripts` for Instagram and the segmented YouTube shape." }, "transcript_format": { "type": "string", "enum": [ "webvtt", "text" ], "description": "TikTok only: the form of the `transcript` string. `webvtt` is WebVTT cues with timestamps (a caption track, or AI transcription of a longer video); `text` is plain text (AI transcription of a shorter video, which also returns `duration_seconds` and `duration_minutes`). Absent on other platforms and when there is no transcript." }, "transcripts": { "type": [ "array", "null" ], "description": "Instagram transcript entries. Each item has a `text` field with the full transcript for that track.", "items": { "type": "object", "description": "Transcript track", "properties": { "text": { "type": "string", "description": "Transcript text" } } } }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } } }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/post/transcript", "data": { "post_id": "1459847961114516", "transcript": "What's the something missing in my life until now, an absence I could not quite place, but knew somehow? And then this vegan bakery came sliding down my screen, and Everdome repair appeared and tightened up my seams. Voila my cherie d, remix french tips and sweet cuisine and let's lit, infinite possibilities I'm down. A world where personalized ads help good ideas get found." }, "credits_used": 0, "request_id": "req_example000000", "cached": true, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/profile/photos": { "get": { "summary": "List Facebook profile photos", "description": "Returns Facebook page or profile photos as unified Post items. Each item includes a photo ID, permalink, full-size image URL, thumbnail, and accessibility caption when available. The photo listing itself carries no author, engagement or date, so on a plain call `post.author`, `post.engagement` and `post.published_at` are null on every row. Send `include=details` and every photo is joined, in the same call, to the per-post lookup for its permalink: the page's name and avatar (`post.author.display_name`, `post.author.avatar_url`) and numeric id (`post.ext.author_id`), the reaction count, the comment count, the share count and the publish time land on each row. What the counts mean depends on the photo: a photo posted on its own carries that post's counts (the photo IS the post), while a photo inside a multi-photo post carries its own counts, which are usually far lower than the post's. The publish time is the post's either way. Photos have no view count, so `post.engagement.views` stays null. Cost: 1 credit for the page plus 1 credit per photo filled from a fresh lookup (8 photos a page, so 9 credits at most); rows already in cache are filled for free, rows that could not be filled are refunded, and a repeat of the same call within the cache window is 0 credits. Time: `include=details` adds 2 to 8 seconds on a fresh page (the lookups run in parallel and the call waits for the slowest, never more than 12 seconds) and nothing when the rows are already cached. The response carries a `hydration` block itemising rows, lookups, cache hits, credits and milliseconds.", "tags": [ "facebook" ], "operationId": "get_facebook_profile_photos", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 9, "x-credit-cost-formula": "1 credit for the page. include=details holds 1 credit per photo (8 a page) and keeps only the rows filled from a fresh lookup, so a page is at most 9 credits; rows served from cache are free, unfilled rows 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": "url", "in": "query", "required": true, "description": "Full URL of the Facebook page or profile. A profile share link (`https://www.facebook.com/share/…`) is accepted.", "schema": { "type": "string" }, "example": "https://www.facebook.com/Meta" }, { "name": "next_page_id", "in": "query", "required": false, "description": "To paginate through to 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": "cursor", "in": "query", "required": false, "description": "To paginate through to the next page", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Set to `details` (one token only) to fill `post.author.display_name`, `post.author.avatar_url`, `post.ext.author_id`, `post.engagement.likes`, `.comments` and `.shares`, and `post.published_at` on every photo in this one call. Holds 1 credit per photo (8 a page) and keeps only the rows filled from a fresh lookup; rows already in cache and rows the lookup cannot fill are refunded, so a page is never more than 9 credits. A photo inside a multi-photo post carries its own counts, not the post's. The join takes 2 to 8 seconds on a fresh page, never more than 12, and nothing when the rows are already cached; read `data.hydration` for the rows, the credits held and kept, and the time. Without it the call is unchanged.", "schema": { "type": "string", "enum": [ "details" ] } }, { "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": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 600 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 3600 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/profile/photos" }, "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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "number", "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": [ "number", "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": [ "number", "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", "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "number", "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; discover reads a country from it into `geo.country` (`source: author_location`). 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": [ "number", "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" }, "link_domain": { "type": [ "string", "null" ], "description": "String at post.ext.link_domain" }, "upvote_ratio": { "type": [ "number", "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" ], "enum": [ "video", "short", "live", "channel", "playlist", 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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "enum": [ "image", "video", "carousel", 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": [ "number", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": { "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": { "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": [ "object", "null" ], "description": "Object 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": { "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/profile/posts`, `/v1/instagram/profile/reels`, `/v1/instagram/search/reels`, `/v1/tiktok/profile/videos` 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": [ "object", "null" ], "description": "Object 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", "enum": [ "image", "video" ], "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "number", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "number", "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": [ "number", "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": [ "object", "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": [ "object", "null" ], "description": "Object at post.ext.retweeted_post" }, "quote_count": { "type": [ "number", "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": { "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": [ "object", "null" ], "description": "Object 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": "object", "description": "Object 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": [ "number", "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": [ "object", "null" ], "description": "Object at post.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: post.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.description" } } } }, "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" ], "enum": [ "minute", "hour", "day", "week", "month", "year", 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": [ "number", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "number", "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": [ "object", "null" ], "description": "Object 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": [ "number", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "object", "null" ], "description": "Object at post.ext.dsp_ids", "additionalProperties": { "type": "string", "description": "String 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": "object", "description": "Object at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "object", "description": "Object at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "object", "description": "Object 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": [ "object", "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": [ "object", "null" ], "description": "Object 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": [ "number", "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": "number", "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": [ "object", "null" ], "description": "Object at post.ext.event" }, "trend": { "type": [ "object", "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" }, "numeric_id": { "type": [ "number", "null" ], "description": "Numeric at post.ext.numeric_id" }, "outbound_url": { "type": [ "string", "null" ], "description": "String at post.ext.outbound_url" }, "group": { "type": [ "object", "null" ], "description": "Object at post.ext.group" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "number", "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": [ "number", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "number", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "number", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "enum": [ "target", "other_named_thing", "generic_word", "not_present" ], "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "number", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "number", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "string", "boolean", "null" ], "description": "Union: number | string | boolean" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } } } } } } }, "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." }, "walk": { "type": "object", "description": "Present when the request sent a row-walk param (`max_pages` above 1, `max_items`, `max_credits`, a row filter, `sort_rows` or `seen`). What the walk did across the pages it fetched. Each page is billed as one call, and its charge is recorded under its own request id.", "properties": { "pages": { "type": "integer", "description": "Pages fetched.", "example": 3 }, "stopped": { "type": "string", "enum": [ "end", "max_pages", "max_items", "max_credits", "time_budget", "page_error" ], "description": "Why the walk stopped. `end`: the list ran out. `max_pages`, `max_items` or `max_credits`: the limit you set was reached. `time_budget`: the request's time budget ran low. `page_error`: a later page failed. Unless it is `end`, `pagination.next_cursor` continues from where the walk stopped.", "example": "max_pages" }, "rows_fetched": { "type": "integer", "description": "Rows read across every page, before any filter.", "example": 60 }, "rows_returned": { "type": "integer", "description": "Rows in `data.items`.", "example": 41 }, "discarded": { "type": "object", "description": "Present when you sent a row filter. Rows the filters removed, counted once each under the first filter they failed. A row a filter cannot verify (no view count, no date, no country) is discarded.", "properties": { "views_below_min": { "type": "integer", "description": "Rows with fewer views than `min_views`." }, "views_unknown": { "type": "integer", "description": "Rows with no view count, when `min_views` was sent." }, "older_than_max_age": { "type": "integer", "description": "Rows published before the `max_age_days` window." }, "date_unknown": { "type": "integer", "description": "Rows with no publish date, when `max_age_days` was sent." }, "country_not_included": { "type": "integer", "description": "Rows registered to a country that is not in `country`." }, "country_unknown": { "type": "integer", "description": "Rows with no country, when `country` was sent." }, "country_excluded": { "type": "integer", "description": "Rows registered to a country listed in `exclude_country`." } } }, "repeats": { "type": "integer", "description": "Present when you sent `seen`: rows removed because your account already received them under that id." }, "duplicates": { "type": "integer", "description": "Present when above zero: rows a later page repeated from an earlier page of the same walk, kept once." }, "credits": { "type": "object", "description": "What the pages cost.", "properties": { "pages": { "type": "integer", "description": "Credits charged for the pages walked, before refunds." }, "refunded": { "type": "integer", "description": "Credits refunded across the pages." } } }, "request_ids": { "type": "array", "description": "The request id of each page walked. Each is its own entry in `GET /v1/credits/transactions`.", "items": { "type": "string", "description": "A row id." } } } }, "hydration": { "type": "object", "description": "Present when the request asked for a row join with `include=`, or sent a param that implies one. What the join did and what it cost. On a multi-page walk it sums every page. A join that always runs for free is left out.", "properties": { "include": { "type": "string", "description": "The token that switched the join on.", "example": "profile" }, "implied_by": { "type": "string", "description": "Present when you did not send `include` and another param switched the join on. The join's credits (`extra_credits`) are then part of `credits_used`. Absent when you sent `include` yourself." }, "rows": { "type": "integer", "description": "Rows on the page after any row cap.", "example": 20 }, "looked_up": { "type": "integer", "description": "Rows that needed a lookup (at least one field the join fills was empty).", "example": 20 }, "filled": { "type": "integer", "description": "Rows where at least one field was filled by the join.", "example": 18 }, "cached": { "type": "integer", "description": "Of `filled`, rows filled from the sibling endpoint's cache at no charge.", "example": 0 }, "unfilled": { "type": "integer", "description": "Rows that needed a lookup and were not filled (the lookup failed, was skipped, or had nothing to copy). Their credits are refunded.", "example": 2 }, "credits_held": { "type": "integer", "description": "Credits held up front for the join, on top of the page's own price.", "example": 20 }, "extra_credits": { "type": "integer", "description": "Of `credits_held`, the credits kept: one lookup's price for each distinct key filled from a fresh lookup. The rest was refunded.", "example": 18 }, "ms": { "type": "integer", "description": "Time the join added, in milliseconds.", "example": 2400 }, "cached_page": { "type": "boolean", "description": "True when the whole page was served from cache, so the join cost nothing on this call.", "example": true }, "batches": { "type": "integer", "description": "Joins that look rows up in batches only: how many batch calls were made. Absent on a join that looks rows up one by one." }, "from_earlier_pages": { "type": "integer", "description": "`max_pages`, `max_items` and `max_credits` walks only: rows filled free from a key already looked up on an earlier page of the same walk. Not counted in `looked_up`, `filled` or `cached`. Absent when zero." }, "steps": { "type": "array", "description": "Present when the request asked for more than one join (`include=engagement,channel`): one report per join, in the order they ran. The top-level numbers are then the page's: rows looked up or filled by any join, and the credits and time of all of them together.", "items": { "type": "object", "description": "One join's report.", "properties": { "include": { "type": "string", "description": "The token that switched the join on.", "example": "profile" }, "implied_by": { "type": "string", "description": "Present when you did not send `include` and another param switched the join on. The join's credits (`extra_credits`) are then part of `credits_used`. Absent when you sent `include` yourself." }, "rows": { "type": "integer", "description": "Rows on the page after any row cap.", "example": 20 }, "looked_up": { "type": "integer", "description": "Rows that needed a lookup (at least one field the join fills was empty).", "example": 20 }, "filled": { "type": "integer", "description": "Rows where at least one field was filled by the join.", "example": 18 }, "cached": { "type": "integer", "description": "Of `filled`, rows filled from the sibling endpoint's cache at no charge.", "example": 0 }, "unfilled": { "type": "integer", "description": "Rows that needed a lookup and were not filled (the lookup failed, was skipped, or had nothing to copy). Their credits are refunded.", "example": 2 }, "credits_held": { "type": "integer", "description": "Credits held up front for the join, on top of the page's own price.", "example": 20 }, "extra_credits": { "type": "integer", "description": "Of `credits_held`, the credits kept: one lookup's price for each distinct key filled from a fresh lookup. The rest was refunded.", "example": 18 }, "ms": { "type": "integer", "description": "Time the join added, in milliseconds.", "example": 2400 }, "cached_page": { "type": "boolean", "description": "True when the whole page was served from cache, so the join cost nothing on this call.", "example": true }, "batches": { "type": "integer", "description": "Joins that look rows up in batches only: how many batch calls were made. Absent on a join that looks rows up one by one." }, "from_earlier_pages": { "type": "integer", "description": "`max_pages`, `max_items` and `max_credits` walks only: rows filled free from a key already looked up on an earlier page of the same walk. Not counted in `looked_up`, `filled` or `cached`. Absent when zero." } } } } } }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/profile/photos", "data": { "items": [ { "post": { "id": "1146841591338383", "url": "https://www.facebook.com/photo.php?fbid=1146841591338383&set=pb.100080376596424.-2207520000&type=3", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://scontent-bos5-1.xx.fbcdn.net/v/t39.30808-6/825292571_1146841521338390_8821495995170295283_n.jpg?stp=cp6_dst-jpg_tt6&cstp=mx852x874&ctp=s852x874&_nc_cat=106&ccb=1-7&_nc_sid=6ee11a&_nc_ohc=idzu8UNXz1IQ7kNvwGSnOHa&_nc_oc=Adq43MQlcUjvdRvfBCzIwglBwz09nSgwcHX4IjwUYgbflPLocBh8LDvxTN-UACBHPT4&_nc_zt=23&_nc_ht=scontent-bos5-1.xx&_nc_gid=02nxsIh9CILBpjMrX_PuPA&_nc_ss=78289&oh=00_AQPW1VrYMp_gT-I2Pd2Gk-XX_cNveDCRqun8usq9CXW5Ig&oe=6AC522C3", "thumbnail_url": "https://scontent-bos5-1.xx.fbcdn.net/v/t39.30808-6/825292571_1146841521338390_8821495995170295283_n.jpg?stp=c0.7.852.852a_cp6_dst-jpg_tt6&cstp=mx852x852&ctp=s552x414&_nc_cat=106&ccb=1-7&_nc_sid=7a06f5&_nc_ohc=idzu8UNXz1IQ7kNvwGSnOHa&_nc_oc=Adq43MQlcUjvdRvfBCzIwglBwz09nSgwcHX4IjwUYgbflPLocBh8LDvxTN-UACBHPT4&_nc_zt=23&_nc_ht=scontent-bos5-1.xx&_nc_gid=02nxsIh9CILBpjMrX_PuPA&_nc_ss=78289&oh=00_AQPh2YMx5nMbDiasxGr8VsM4Y6PllI4_LSzw6NjsU7zjLw&oe=6AC522C3", "duration_seconds": null }, "author": { "username": null, "display_name": null, "avatar_url": null, "verified": null }, "engagement": { "views": null, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": null }, "computed": { "engagement_rate": null, "language": null, "content_category": "other", "estimated_reach": null } }, { "post": { "id": "1146841184671757", "url": "https://www.facebook.com/photo.php?fbid=1146841184671757&set=pb.100080376596424.-2207520000&type=3", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://scontent-bos5-1.xx.fbcdn.net/v/t39.30808-6/825292146_1146841188005090_7443674991975795954_n.jpg?stp=cp6_dst-jpg_tt6&cstp=mx3366x1246&ctp=s3366x1246&_nc_cat=108&ccb=1-7&_nc_sid=cc71e4&_nc_ohc=vncXg57GIL0Q7kNvwGVtlOL&_nc_oc=Adrj947TciPZgkhDyvE5ZWQMHWjfNoW_JLhEUBBMshA3qjKTPjeJSX7pxFijx25AeNY&_nc_zt=23&_nc_ht=scontent-bos5-1.xx&_nc_gid=02nxsIh9CILBpjMrX_PuPA&_nc_ss=78289&oh=00_AQN0irDysrVb7MZPf2_JMSRbb0lruiHm3vMoK4EwyxBtaQ&oe=6AC528B0", "thumbnail_url": "https://scontent-bos5-1.xx.fbcdn.net/v/t39.30808-6/825292146_1146841188005090_7443674991975795954_n.jpg?stp=c1060.0.1246.1246a_cp6_dst-jpg_tt6&cstp=mx1246x1246&ctp=s552x414&_nc_cat=108&ccb=1-7&_nc_sid=52bb43&_nc_ohc=vncXg57GIL0Q7kNvwGVtlOL&_nc_oc=Adrj947TciPZgkhDyvE5ZWQMHWjfNoW_JLhEUBBMshA3qjKTPjeJSX7pxFijx25AeNY&_nc_zt=23&_nc_ht=scontent-bos5-1.xx&_nc_gid=02nxsIh9CILBpjMrX_PuPA&_nc_ss=78289&oh=00_AQPk7K6BZ3BtR4d2EMKzMGidLilX15ki4XauqBL2wzlAhA&oe=6AC528B0", "duration_seconds": null }, "author": { "username": null, "display_name": null, "avatar_url": null, "verified": null }, "engagement": { "views": null, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": null }, "computed": { "engagement_rate": null, "language": null, "content_category": "other", "estimated_reach": null } } ], "next_cursor": "scp.eyJ2IjoxLCJxIjp7Im5leHRfcGFnZV9pZCI6IllYQndYMk52Ykd4bFkzUnBiMjQ2Y0daaWFXUXdNMlZhZUhGb1pXcGlRV001ZG5OTWVUUm1lbE5PT0d0YWVYUm1Xa1ZsVTBVNFRXZEtjRXBUZW1kaWNHZGllRTQwTkdOU2JYVk1XbTFrVnpoNFpWbExOMGRZVGxJeU9EbG5hVU5ZZUdobFZVSTFia3h5ZVhKQ2R6a3lSbk5zIiwiY3Vyc29yIjoiQVFIVHMwNHRWTGpOa21KcjZIeTFjVmxFZmUwSmlUNUdOaVVvNlZrdVl2Y0d0Q2ZzR3hLVENSSVRrVXNwTE9mM1lmaWpsaG1Ib2czdFliR1ktaXVUT2M3V19RIn19", "total": null, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoic2NwLmV5SjJJam94TENKeElqcDdJbTVsZUhSZmNHRm5aVjlwWkNJNklsbFlRbmRZTWs1MllrZDRiRmt6VW5CaU1qUTJZMGRhYVdGWFVYZE5NbFpoWlVoR2IxcFhjR2xSVjAwMVpHNU9UV1ZVVW0xbGJFNVBUMGQwWVdWWVVtMVhhMVpzVlRCVk5GUlhaRXRqUlhCVVpXMWthV05IWkdsbFJUUXdUa2RPVTJKWVZrMVhiVEZyVm5wb05GcFdiRXhPTUdSWlZHeEplVTlFYkc1aFZVNVpaVWRvYkZaVlNURmlhM2g1WlZoS1EyUjZhM2xTYms1eklpd2lZM1Z5YzI5eUlqb2lRVkZJVkhNd05IUldUR3BPYTIxS2NqWkllVEZqVm14RlptVXdTbWxVTlVkT2FWVnZObFpyZFZsMlkwZDBRMlp6UjNoTFZFTlNTVlJyVlhOd1RFOW1NMWxtYVdwc2FHMUliMmN6ZEZsaVIxa3RhWFZVVDJNM1YxOVJJbjE5IiwiZSI6ImZhY2Vib29rL3Byb2ZpbGUvcGhvdG9zIiwicCI6Im5leHRfcGFnZV9pZCJ9", "has_more": true, "page_size": 8 }, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/profile/reels": { "get": { "summary": "List Facebook profile reels", "description": "Returns Facebook page or profile reels as unified Post items. Each item includes a reel ID, description, thumbnail, duration when available, author identity, `engagement.views` when the upstream provides it, permalink, and publish time. Likes, comments, shares, and saves remain null because this endpoint does not expose those counts. **Two caveats worth knowing before you grade on these numbers:** (1) `engagement.views` here is Facebook's ROUNDED public display value (the \"12K\" / \"2.6M\" the page shows, parsed back to a number: e.g. 12000 where the true count is 12366), not an exact count; (2) the upstream carries no per-reel engagement beyond that view count. A third, on pagination: on a page with only a handful of reels the first response can report `pagination.has_more: true` and the next page then come back empty, because the upstream mints a cursor it cannot fill. The empty page is free, so this costs a round trip rather than a credit. For EXACT views plus likes, comments, and shares, the easiest path is `GET /v1/facebook/profile/reels/full`, which runs this list and the per-reel lookups server-side and merges the exact engagement in (flat 5 credits per page of 10 reels). Alternatively, take each item's `post.url` and pass it to `/v1/facebook/post` (single) or batch up to 100 of them into `POST /v1/prism/post-stats` (1 credit per successful URL, dead links refunded).", "tags": [ "facebook" ], "operationId": "get_facebook_profile_reels", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full URL of the Facebook page or profile. A profile share link (`https://www.facebook.com/share/…`) is accepted.", "schema": { "type": "string" }, "example": "https://www.facebook.com/Meta" }, { "name": "next_page_id", "in": "query", "required": false, "description": "To paginate through to 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": "cursor", "in": "query", "required": false, "description": "To paginate through to the next page", "schema": { "type": "string" } }, { "name": "recent_days", "in": "query", "required": false, "description": "Keep only reels published in the last N days (1 to 3650) and stop pagination once a page reaches older reels. Does not change the price of a page.", "schema": { "type": "integer", "minimum": 1, "maximum": 3650 } }, { "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": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 600 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 3600 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/profile/reels" }, "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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "number", "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": [ "number", "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": [ "number", "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", "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "number", "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; discover reads a country from it into `geo.country` (`source: author_location`). 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": [ "number", "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" }, "link_domain": { "type": [ "string", "null" ], "description": "String at post.ext.link_domain" }, "upvote_ratio": { "type": [ "number", "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" ], "enum": [ "video", "short", "live", "channel", "playlist", 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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "enum": [ "image", "video", "carousel", 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": [ "number", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": { "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": { "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": [ "object", "null" ], "description": "Object 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": { "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/profile/posts`, `/v1/instagram/profile/reels`, `/v1/instagram/search/reels`, `/v1/tiktok/profile/videos` 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": [ "object", "null" ], "description": "Object 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", "enum": [ "image", "video" ], "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "number", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "number", "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": [ "number", "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": [ "object", "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": [ "object", "null" ], "description": "Object at post.ext.retweeted_post" }, "quote_count": { "type": [ "number", "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": { "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": [ "object", "null" ], "description": "Object 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": "object", "description": "Object 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": [ "number", "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": [ "object", "null" ], "description": "Object at post.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: post.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.description" } } } }, "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" ], "enum": [ "minute", "hour", "day", "week", "month", "year", 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": [ "number", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "number", "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": [ "object", "null" ], "description": "Object 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": [ "number", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "object", "null" ], "description": "Object at post.ext.dsp_ids", "additionalProperties": { "type": "string", "description": "String 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": "object", "description": "Object at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "object", "description": "Object at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "object", "description": "Object 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": [ "object", "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": [ "object", "null" ], "description": "Object 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": [ "number", "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": "number", "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": [ "object", "null" ], "description": "Object at post.ext.event" }, "trend": { "type": [ "object", "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" }, "numeric_id": { "type": [ "number", "null" ], "description": "Numeric at post.ext.numeric_id" }, "outbound_url": { "type": [ "string", "null" ], "description": "String at post.ext.outbound_url" }, "group": { "type": [ "object", "null" ], "description": "Object at post.ext.group" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "number", "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": [ "number", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "number", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "number", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "enum": [ "target", "other_named_thing", "generic_word", "not_present" ], "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "number", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "number", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "string", "boolean", "null" ], "description": "Union: number | string | boolean" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } } } } } } }, "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." }, "walk": { "type": "object", "description": "Present when the request sent a row-walk param (`max_pages` above 1, `max_items`, `max_credits`, a row filter, `sort_rows` or `seen`). What the walk did across the pages it fetched. Each page is billed as one call, and its charge is recorded under its own request id.", "properties": { "pages": { "type": "integer", "description": "Pages fetched.", "example": 3 }, "stopped": { "type": "string", "enum": [ "end", "max_pages", "max_items", "max_credits", "time_budget", "page_error" ], "description": "Why the walk stopped. `end`: the list ran out. `max_pages`, `max_items` or `max_credits`: the limit you set was reached. `time_budget`: the request's time budget ran low. `page_error`: a later page failed. Unless it is `end`, `pagination.next_cursor` continues from where the walk stopped.", "example": "max_pages" }, "rows_fetched": { "type": "integer", "description": "Rows read across every page, before any filter.", "example": 60 }, "rows_returned": { "type": "integer", "description": "Rows in `data.items`.", "example": 41 }, "discarded": { "type": "object", "description": "Present when you sent a row filter. Rows the filters removed, counted once each under the first filter they failed. A row a filter cannot verify (no view count, no date, no country) is discarded.", "properties": { "views_below_min": { "type": "integer", "description": "Rows with fewer views than `min_views`." }, "views_unknown": { "type": "integer", "description": "Rows with no view count, when `min_views` was sent." }, "older_than_max_age": { "type": "integer", "description": "Rows published before the `max_age_days` window." }, "date_unknown": { "type": "integer", "description": "Rows with no publish date, when `max_age_days` was sent." }, "country_not_included": { "type": "integer", "description": "Rows registered to a country that is not in `country`." }, "country_unknown": { "type": "integer", "description": "Rows with no country, when `country` was sent." }, "country_excluded": { "type": "integer", "description": "Rows registered to a country listed in `exclude_country`." } } }, "repeats": { "type": "integer", "description": "Present when you sent `seen`: rows removed because your account already received them under that id." }, "duplicates": { "type": "integer", "description": "Present when above zero: rows a later page repeated from an earlier page of the same walk, kept once." }, "credits": { "type": "object", "description": "What the pages cost.", "properties": { "pages": { "type": "integer", "description": "Credits charged for the pages walked, before refunds." }, "refunded": { "type": "integer", "description": "Credits refunded across the pages." } } }, "request_ids": { "type": "array", "description": "The request id of each page walked. Each is its own entry in `GET /v1/credits/transactions`.", "items": { "type": "string", "description": "A row id." } } } }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/profile/reels", "data": { "items": [ { "post": { "id": "1152729184082957", "url": "https://www.facebook.com/reel/2277713513083702", "content": { "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "media_urls": "https://scontent-bos5-1.xx.fbcdn.net/v/t15.5256-10/808190330_2551818145314526_456542767254010348_n.jpg?stp=dst-jpg_tt6&cstp=mx1080x1920&ctp=p960x960&_nc_cat=108&ccb=1-7&_nc_sid=5fad0e&_nc_ohc=b71k3ILihV8Q7kNvwHxwqMN&_nc_oc=Adqdz4eVzfaa9ETnvFhVscPgxVWZTiJVc6OjMuyYPliB3LYzeDPo--4gDcyDy4znjPI&_nc_zt=23&_nc_ht=scontent-bos5-1.xx&_nc_gid=QpTiMwpaNc7ChxHLJZx4Vw&_nc_ss=78289&oh=00_AQOVmqUJQ2irV1WGE0U2oCF7tgvSYm0H0f2Up7de-957_A&oe=6AC5302C", "thumbnail_url": "https://scontent-bos5-1.xx.fbcdn.net/v/t15.5256-10/808190330_2551818145314526_456542767254010348_n.jpg?stp=dst-jpg_tt6&cstp=mx1080x1920&ctp=p960x960&_nc_cat=108&ccb=1-7&_nc_sid=5fad0e&_nc_ohc=b71k3ILihV8Q7kNvwHxwqMN&_nc_oc=Adqdz4eVzfaa9ETnvFhVscPgxVWZTiJVc6OjMuyYPliB3LYzeDPo--4gDcyDy4znjPI&_nc_zt=23&_nc_ht=scontent-bos5-1.xx&_nc_gid=QpTiMwpaNc7ChxHLJZx4Vw&_nc_ss=78289&oh=00_AQOVmqUJQ2irV1WGE0U2oCF7tgvSYm0H0f2Up7de-957_A&oe=6AC5302C", "duration_seconds": 74.645 }, "author": { "username": null, "display_name": "Meta", "avatar_url": "https://example.com/avatars/user_67ab50.png", "verified": true }, "engagement": { "views": 22000, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-10-01T16:16:02.000Z", "ext": { "author_id": "user_9cf871", "music": { "id": "28628413730132185", "track_title": "Meta · Original audio" }, "feedback_id": "ZmVlZGJhY2s6MTE1MjcyOTE4NDA4Mjk1Nw==" } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": 26400 } }, { "post": { "id": "1151655277523681", "url": "https://www.facebook.com/reel/1737837581070505", "content": { "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "media_urls": "https://scontent-bos5-1.xx.fbcdn.net/v/t15.5256-10/796250406_1128825959830539_5799221356349284506_n.jpg?stp=dst-jpg_tt6&cstp=mx1080x1920&ctp=p960x960&_nc_cat=108&ccb=1-7&_nc_sid=5fad0e&_nc_ohc=8xQLrvZJP94Q7kNvwEbT5bd&_nc_oc=AdoSELgUKI6KXR4xxFXol8B9tOtK0c0Q0-WqQcft-W23noYGEiv0KMJVSUbnhNWs29c&_nc_zt=23&_nc_ht=scontent-bos5-1.xx&_nc_gid=QpTiMwpaNc7ChxHLJZx4Vw&_nc_ss=78289&oh=00_AQNVQk1vmLMaA1V5mhoDShDCjwjiYFaQdMllDffat0HgkQ&oe=6AC54A16", "thumbnail_url": "https://scontent-bos5-1.xx.fbcdn.net/v/t15.5256-10/796250406_1128825959830539_5799221356349284506_n.jpg?stp=dst-jpg_tt6&cstp=mx1080x1920&ctp=p960x960&_nc_cat=108&ccb=1-7&_nc_sid=5fad0e&_nc_ohc=8xQLrvZJP94Q7kNvwEbT5bd&_nc_oc=AdoSELgUKI6KXR4xxFXol8B9tOtK0c0Q0-WqQcft-W23noYGEiv0KMJVSUbnhNWs29c&_nc_zt=23&_nc_ht=scontent-bos5-1.xx&_nc_gid=QpTiMwpaNc7ChxHLJZx4Vw&_nc_ss=78289&oh=00_AQNVQk1vmLMaA1V5mhoDShDCjwjiYFaQdMllDffat0HgkQ&oe=6AC54A16", "duration_seconds": 82.666 }, "author": { "username": null, "display_name": "Meta", "avatar_url": "https://example.com/avatars/user_67ab50.png", "verified": true }, "engagement": { "views": 75000, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-30T16:08:10.000Z", "ext": { "author_id": "user_9cf871", "music": { "id": "38894363146845235", "track_title": "Meta · Original audio" }, "feedback_id": "ZmVlZGJhY2s6MTE1MTY1NTI3NzUyMzY4MQ==" } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": 90000 } } ], "next_cursor": "sc2.eyJzIjoiYiIsImMiOiJzY3AuZXlKMklqb3hMQ0p4SWpwN0ltNWxlSFJmY0dGblpWOXBaQ0k2SWxsWVFuZFlNazUyWWtkNGJGa3pVbkJpTWpRMlkwZGFhV0ZYVVhkVlZsWjVWbFZ3Vm1Rd1VsSlNTRXByVTBjeFZGVkVValJhYlVwTFZFWndWMkZ0Y0dGVVNIQkVaV3RPUTA5R1ZrbGhhbXd5VWtSS1ZtVnRVWGhaTUU1UlYwWnNWRlpYZEhGbGFtaDVXVzFHTlU5WFJrTldWa295WlZWU1RGb3dSbTFSVjJ0NldURkdZVTVZV2paWmJHaFJUbTFHVFU5SGRGSlNSa1pPWkVSYU1WbHJiekZqTTNCeklpd2lZM1Z5YzI5eUlqb2lRVkZJVkd4WmFEWklWRkZIV0hneWFFRXpTVk42Tm0xdmRWWTRXSFU1VEhWUVpqVkRNMWwwYlhkTGJsQnFaSGRNZDA4MGQwNTJNa3gwWWpkS1ZVaE5iVkpRWkdVdFJVRnZTVTlCVGw5bFZFOUZiamhXTFU4elNYbDNJbjE5In0", "total": null, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWWlJc0ltTWlPaUp6WTNBdVpYbEtNa2xxYjNoTVEwcDRTV3B3TjBsdE5XeGxTRkptWTBkR2JscFdPWEJhUTBrMlNXeHNXVkZ1WkZsTmF6VXlXV3RrTkdKR2EzcFZia0pwVFdwUk1sa3daR0ZoVjBaWVZWaGtWbFpzV2pWV2JGWjNWbTFSZDFWc1NsTlRSWEJ5VlRCamVGWkdWa1ZWYWxKaFlsVndURlpGV25kV01rWjBZMGRHVlZOSVFrVmFWM1JQVVRBNVIxWnJiR2hoYlhkNVZXdFNTMVp0Vm5SVldHaGFUVVUxVWxZd1duTldSbHBZWkVoR2JHRnRhRFZYVnpGSFRsVTVXRkpyVGxkV2EyOTVXbFpXVTFSR2IzZFNiVEZTVmpKME5sZFVSa2RaVlRWWlYycGFXbUpIYUZKVWJURkhWRlU1U0dSR1NsTlNhMXBQV2tWU1lVMVdiSEppZWtacVRUTkNla2xwZDJsWk0xWjVZekk1ZVVscWIybFJWa1pKVmtkNFdtRkVXa2xXUmtaSVYwaG5lV0ZGUlhwVFZrNDJUbTB4ZG1SV1dUUlhTRlUxVkVoV1VWcHFWa1JOTVd3d1lsaGtUR0pzUW5GYVNHUk5aREE0TUdRd05USk5hM2d3V1dwa1MxWlZhRTVpVmtwUldrZFZkRkpWUm5aVFZUbENWR3c1YkZaRk9VWmlhbWhYVEZVNGVsTlliRE5KYmpFNUluMCIsImUiOiJmYWNlYm9vay9wcm9maWxlL3JlZWxzIiwicCI6Im5leHRfcGFnZV9pZCJ9", "has_more": true, "page_size": 10 }, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/adlibrary/ad": { "get": { "summary": "Get Facebook Ad Library ad details", "description": "Returns one ad from the Facebook Ad Library. Video creatives land in `content.media_urls` (playable URL) and `content.thumbnail_url` (preview frame); every ad signal rides the `post.ext.ad` envelope: CTA text and type, `link_url`, `is_active`, `end_date_iso`, `display_format`, `title`, `publisher_platforms`, `categories`, the video URLs, and the advertiser's own `page_id`, `page_profile_uri` (their Facebook page, so you can chain straight to `/v1/facebook/profile`), `page_like_count` and `page_categories`. **`spend`, `reach_estimate` and `currency` are populated by Facebook for POLITICAL and issue ads only** and read null or empty on a commercial ad; Facebook publishes no per-ad impression count outside that same political set, so there is no impressions figure to return. `post.author.username` is null by design: an Ad Library record carries the page NAME, not its handle, and a name is not a handle. An ad has no public view count, so `engagement.views` carries Facebook's audience REACH ESTIMATE where one exists (political and issue ads) and is null everywhere else; the same figure is on `post.ext.ad.reach_estimate` under its real name, and `computed.engagement_rate` is derived from it rather than from any real engagement. `published_at` is the ad's first-run DATE; the `07:00:00Z` clock component on every row is an artefact of Facebook storing ad dates on a US Pacific day boundary and carries no sub-day meaning. On an ad that ran in the EU, Facebook publishes who saw it: `post.ext.ad.eu_total_reach` is the total EU reach, `post.ext.ad.eu_reach_breakdown` lists each EU country with that reach split into age bands (18-24 to 65+) by `male`, `female` and `unknown`, and `post.ext.ad.targets_eu`, `target_ages`, `target_gender` and `target_locations` are who the advertiser targeted. An ad that never ran in the EU carries none of these, and they read null. For ad video transcripts use `/v1/facebook/adlibrary/ad/transcript` (separate endpoint, premium tier).", "tags": [ "facebook" ], "operationId": "get_facebook_adlibrary_ad", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "x-socialcrawl-oneOf": [ [ "id", "url" ] ], "parameters": [ { "name": "id", "in": "query", "required": false, "description": "Facebook Ad Library ad ID. Ad ids rotate as campaigns end, so take a current one from `/v1/facebook/adlibrary/company/ads` or `/v1/facebook/adlibrary/search/ads` rather than reusing an old one. (one of: id, url; at least one required)", "schema": { "type": "string" }, "example": "1702938977100376" }, { "name": "url", "in": "query", "required": false, "description": "Facebook Ad Library URL for the ad (`https://www.facebook.com/ads/library?id=...`). A page URL is rejected with a 400 at 0 credits. (one of: id, url; at least one required)", "schema": { "type": "string" } }, { "name": "trim", "in": "query", "required": false, "description": "Set to true for a trimmed down version of the response", "schema": { "type": "boolean" } }, { "name": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 1800 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 1800 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/adlibrary/ad" }, "data": { "type": "object", "description": "Platform-specific response data", "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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "number", "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": [ "number", "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": [ "number", "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", "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "number", "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; discover reads a country from it into `geo.country` (`source: author_location`). 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": [ "number", "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" }, "link_domain": { "type": [ "string", "null" ], "description": "String at post.ext.link_domain" }, "upvote_ratio": { "type": [ "number", "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" ], "enum": [ "video", "short", "live", "channel", "playlist", 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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "enum": [ "image", "video", "carousel", 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": [ "number", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": { "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": { "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": [ "object", "null" ], "description": "Object 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": { "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/profile/posts`, `/v1/instagram/profile/reels`, `/v1/instagram/search/reels`, `/v1/tiktok/profile/videos` 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": [ "object", "null" ], "description": "Object 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", "enum": [ "image", "video" ], "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "number", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "number", "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": [ "number", "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": [ "object", "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": [ "object", "null" ], "description": "Object at post.ext.retweeted_post" }, "quote_count": { "type": [ "number", "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": { "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": [ "object", "null" ], "description": "Object 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": "object", "description": "Object 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": [ "number", "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": [ "object", "null" ], "description": "Object at post.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: post.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.description" } } } }, "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" ], "enum": [ "minute", "hour", "day", "week", "month", "year", 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": [ "number", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "number", "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": [ "object", "null" ], "description": "Object 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": [ "number", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "object", "null" ], "description": "Object at post.ext.dsp_ids", "additionalProperties": { "type": "string", "description": "String 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": "object", "description": "Object at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "object", "description": "Object at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "object", "description": "Object 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": [ "object", "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": [ "object", "null" ], "description": "Object 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": [ "number", "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": "number", "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": [ "object", "null" ], "description": "Object at post.ext.event" }, "trend": { "type": [ "object", "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" }, "numeric_id": { "type": [ "number", "null" ], "description": "Numeric at post.ext.numeric_id" }, "outbound_url": { "type": [ "string", "null" ], "description": "String at post.ext.outbound_url" }, "group": { "type": [ "object", "null" ], "description": "Object at post.ext.group" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "number", "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": [ "number", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "number", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "number", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "enum": [ "target", "other_named_thing", "generic_word", "not_present" ], "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "number", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "number", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "string", "boolean", "null" ], "description": "Union: number | string | boolean" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } } } }, "_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": [ "post" ] }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/adlibrary/ad", "data": { "post": { "id": "1702938977100376", "url": "https://www.facebook.com/ads/library?id=1702938977100376", "content": { "text": "Bring sports more fully into your day with the Nike App.", "media_urls": [ "https://scontent-iad6-1.xx.fbcdn.net/v/t39.35426-6/431644642_737508601479774_8272309847273720820_n.jpg?_nc_cat=102&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=vnzhHfbNDoYQ7kNvwFR_7Ce&_nc_oc=Adp0orT-UKwnBWQeVYkt3ZVfpMZ_QWC7uayKLPLi2C7fYfm7-_pPjRPeK7jx2Vo_BB4&_nc_zt=14&_nc_ht=scontent-iad6-1.xx&_nc_gid=WMMONsHbmrH7xgysxW6OEg&_nc_ss=78289&oh=00_AQOPCc6--nHygyqzA1g_YVTHCST1Ub1xT043ToQRUz6xEQ&oe=6AC5A203", "https://scontent-iad6-1.xx.fbcdn.net/v/t39.35426-6/431679131_949214166636263_7090981238489979310_n.jpg?_nc_cat=100&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=_PGRVKv7_wsQ7kNvwGK87vn&_nc_oc=AdpzUCNj1EcgYWMNGogrXditJxh6XCHupS-v560CLAqzZ8rEnEpjJTkpNLvYJLzUMbU&_nc_zt=14&_nc_ht=scontent-iad6-1.xx&_nc_gid=WMMONsHbmrH7xgysxW6OEg&_nc_ss=78289&oh=00_AQO8K6YfVO8X4rAfLtxqB0u3xWvZHLQ7lwG1xetxDIZNdQ&oe=6AC5B751" ], "thumbnail_url": "https://scontent-iad6-1.xx.fbcdn.net/v/t39.35426-6/431644642_737508601479774_8272309847273720820_n.jpg?_nc_cat=102&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=vnzhHfbNDoYQ7kNvwFR_7Ce&_nc_oc=Adp0orT-UKwnBWQeVYkt3ZVfpMZ_QWC7uayKLPLi2C7fYfm7-_pPjRPeK7jx2Vo_BB4&_nc_zt=14&_nc_ht=scontent-iad6-1.xx&_nc_gid=WMMONsHbmrH7xgysxW6OEg&_nc_ss=78289&oh=00_AQOPCc6--nHygyqzA1g_YVTHCST1Ub1xT043ToQRUz6xEQ&oe=6AC5A203", "duration_seconds": null }, "author": { "username": null, "display_name": "Nike", "avatar_url": "https://scontent-iad3-1.xx.fbcdn.net/v/t39.35426-6/431756959_712871054375981_2401799800446082357_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=104&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=QiJ8JxACRTsQ7kNvwGaIDNC&_nc_oc=AdrjFQ1sqGZEfMAu57gXkPUmUIyestjFvK8M7o8RPDAMVTMP4gqSS1ztxJarGK87wSg&_nc_zt=14&_nc_ht=scontent-iad3-1.xx&_nc_gid=WMMONsHbmrH7xgysxW6OEg&_nc_ss=78289&oh=00_AQNC3VdCMsPqVL45f5f3mW8P4lGrnsedmF_MEQAShKFFog&oe=6AC5A406", "verified": null }, "engagement": { "views": null, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2025-04-07T07:00:00.000Z", "ext": { "ad": { "page_id": "15087023444", "currency": "", "spend": null, "reach_estimate": null, "publisher_platforms": [ "facebook", "instagram" ], "categories": [ "UNKNOWN" ], "cta_text": "Install now", "cta_type": "INSTALL_MOBILE_APP", "link_url": "http://itunes.apple.com/app/id1095459556", "is_active": true, "end_date_iso": "2026-10-02T07:00:00.000Z", "display_format": "DPA", "title": "Cosmic Unity 3 Basketball Shoes", "page_profile_uri": "https://www.facebook.com/nike/", "page_like_count": 39509712, "page_categories": [ "Sportswear", "Product/service" ], "caption": "itunes.apple.com", "video_hd_url": null, "video_sd_url": null } } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": null } }, "credits_used": 5, "request_id": "req_example000000", "cached": false, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/adlibrary/company/ads": { "get": { "summary": "List Facebook Ad Library company ads", "description": "Returns ads from one company or page in the Facebook Ad Library, ordered by impressions or recency depending on `sort_by`. Same per-ad shape as `/v1/facebook/adlibrary/ad`: video creatives in `content.media_urls` and `content.thumbnail_url`, every ad signal on the `post.ext.ad` envelope (CTA, `link_url`, active status, dates, display format, headline, video URLs, plus the advertiser's `page_profile_uri`, `page_like_count` and `page_categories`). **`spend` and `reach_estimate` are populated for POLITICAL and issue ads only** and read null on commercial advertisers. `engagement.views` carries Facebook's audience REACH ESTIMATE, not a view count (an ad has no public view count); it is null on commercial advertisers and the same figure rides `post.ext.ad.reach_estimate` under its real name. `published_at` is the ad's first-run DATE: the `07:00:00Z` clock component is an artefact of Facebook's US Pacific day boundary and carries no sub-day meaning. `post.author.username` is null by design (an Ad Library record carries the page name, not its handle). A plain row carries no audience breakdown. Send `include=audience` and every ad is joined, in the same call, to the per-ad lookup: on an ad that ran in the EU, `post.ext.ad.eu_total_reach` is the total EU reach, `post.ext.ad.eu_reach_breakdown` lists each EU country with that reach split into age bands (18-24 to 65+) by `male`, `female` and `unknown`, and `target_ages`, `target_gender` and `target_locations` are who the advertiser targeted. These are counts Facebook publishes under EU transparency rules, so an ad that never ran in the EU has none of them and its row is refunded. Cost: 5 credits for the page plus 1 credit per ad filled from a fresh lookup (30 ads a page, so 35 credits at most); rows already in cache are free, rows that could not be filled are refunded, and a repeat of the same call within the cache window is 0 credits. Time: `include=audience` adds 3 to 6 seconds on a fresh page (the lookups run in parallel and the call waits for the slowest, never more than 12 seconds). The response carries a `hydration` block itemising rows, lookups, cache hits, credits and milliseconds.", "tags": [ "facebook" ], "operationId": "get_facebook_adlibrary_company_ads", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "x-credit-cost-min": 5, "x-credit-cost-max": 35, "x-credit-cost-formula": "5 credits for the page. include=audience holds 1 credit per ad (30 a page) and keeps only the rows filled from a fresh lookup, so a page is at most 35 credits; rows served from cache are free, ads that never ran in the EU and other unfilled rows 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.", "x-socialcrawl-oneOf": [ [ "pageId", "companyName" ] ], "parameters": [ { "name": "pageId", "in": "query", "required": false, "description": "Facebook page ID of the advertiser (one of: pageId, companyName; at least one required)", "schema": { "type": "string" } }, { "name": "companyName", "in": "query", "required": false, "description": "The name of the company. Can either use this or pageId (one of: pageId, companyName; at least one required)", "schema": { "type": "string" }, "example": "Lululemon" }, { "name": "country", "in": "query", "required": false, "description": "This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Status of the ad. Defaults to ACTIVE.", "schema": { "type": "string", "enum": [ "ALL", "ACTIVE", "INACTIVE" ] } }, { "name": "media_type", "in": "query", "required": false, "description": "Media type of the ad. Defaults to ALL. Meme refers to ads with image and text. Not sure why they call it meme.", "schema": { "type": "string", "enum": [ "ALL", "IMAGE", "VIDEO", "MEME", "IMAGE_AND_MEME", "NONE" ] } }, { "name": "language", "in": "query", "required": false, "description": "Language to filter ads on. Needs to be 2 letter language code, ie EN, ES, FR, etc", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions.", "schema": { "type": "string", "enum": [ "total_impressions", "relevancy_monthly_grouped" ] } }, { "name": "start_date", "in": "query", "required": false, "description": "Start date to search for. Format: YYYY-MM-DD", "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "description": "End date to search for. Format: YYYY-MM-DD", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor to paginate through results", "schema": { "type": "string" } }, { "name": "trim", "in": "query", "required": false, "description": "Set to true for a trimmed down version of the response", "schema": { "type": "boolean" } }, { "name": "include", "in": "query", "required": false, "description": "Set to `audience` (one token only) to fill, on every ad that ran in the EU, `post.ext.ad.eu_total_reach`, `post.ext.ad.eu_reach_breakdown` (reach per EU country by age band and gender), `post.ext.ad.targets_eu`, `target_ages`, `target_gender` and `target_locations`. Holds 1 credit per ad (30 a page) and keeps only the rows filled from a fresh lookup; rows already in cache, ads that never ran in the EU and rows the lookup cannot fill are refunded, so a page is never more than 35 credits. The join takes 3 to 6 seconds on a fresh page, never more than 12 seconds a row, and nothing when the rows are already cached; read `data.hydration` for the rows, the credits held and kept, and the time. Without it the call is unchanged.", "schema": { "type": "string", "enum": [ "audience" ] } }, { "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": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 1800 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 1800 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/adlibrary/company/ads" }, "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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "number", "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": [ "number", "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": [ "number", "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", "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "number", "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; discover reads a country from it into `geo.country` (`source: author_location`). 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": [ "number", "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" }, "link_domain": { "type": [ "string", "null" ], "description": "String at post.ext.link_domain" }, "upvote_ratio": { "type": [ "number", "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" ], "enum": [ "video", "short", "live", "channel", "playlist", 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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "enum": [ "image", "video", "carousel", 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": [ "number", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": { "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": { "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": [ "object", "null" ], "description": "Object 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": { "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/profile/posts`, `/v1/instagram/profile/reels`, `/v1/instagram/search/reels`, `/v1/tiktok/profile/videos` 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": [ "object", "null" ], "description": "Object 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", "enum": [ "image", "video" ], "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "number", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "number", "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": [ "number", "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": [ "object", "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": [ "object", "null" ], "description": "Object at post.ext.retweeted_post" }, "quote_count": { "type": [ "number", "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": { "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": [ "object", "null" ], "description": "Object 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": "object", "description": "Object 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": [ "number", "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": [ "object", "null" ], "description": "Object at post.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: post.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.description" } } } }, "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" ], "enum": [ "minute", "hour", "day", "week", "month", "year", 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": [ "number", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "number", "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": [ "object", "null" ], "description": "Object 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": [ "number", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "object", "null" ], "description": "Object at post.ext.dsp_ids", "additionalProperties": { "type": "string", "description": "String 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": "object", "description": "Object at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "object", "description": "Object at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "object", "description": "Object 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": [ "object", "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": [ "object", "null" ], "description": "Object 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": [ "number", "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": "number", "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": [ "object", "null" ], "description": "Object at post.ext.event" }, "trend": { "type": [ "object", "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" }, "numeric_id": { "type": [ "number", "null" ], "description": "Numeric at post.ext.numeric_id" }, "outbound_url": { "type": [ "string", "null" ], "description": "String at post.ext.outbound_url" }, "group": { "type": [ "object", "null" ], "description": "Object at post.ext.group" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "number", "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": [ "number", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "number", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "number", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "enum": [ "target", "other_named_thing", "generic_word", "not_present" ], "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "number", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "number", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "string", "boolean", "null" ], "description": "Union: number | string | boolean" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } } } } } } }, "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." }, "walk": { "type": "object", "description": "Present when the request sent a row-walk param (`max_pages` above 1, `max_items`, `max_credits`, a row filter, `sort_rows` or `seen`). What the walk did across the pages it fetched. Each page is billed as one call, and its charge is recorded under its own request id.", "properties": { "pages": { "type": "integer", "description": "Pages fetched.", "example": 3 }, "stopped": { "type": "string", "enum": [ "end", "max_pages", "max_items", "max_credits", "time_budget", "page_error" ], "description": "Why the walk stopped. `end`: the list ran out. `max_pages`, `max_items` or `max_credits`: the limit you set was reached. `time_budget`: the request's time budget ran low. `page_error`: a later page failed. Unless it is `end`, `pagination.next_cursor` continues from where the walk stopped.", "example": "max_pages" }, "rows_fetched": { "type": "integer", "description": "Rows read across every page, before any filter.", "example": 60 }, "rows_returned": { "type": "integer", "description": "Rows in `data.items`.", "example": 41 }, "discarded": { "type": "object", "description": "Present when you sent a row filter. Rows the filters removed, counted once each under the first filter they failed. A row a filter cannot verify (no view count, no date, no country) is discarded.", "properties": { "views_below_min": { "type": "integer", "description": "Rows with fewer views than `min_views`." }, "views_unknown": { "type": "integer", "description": "Rows with no view count, when `min_views` was sent." }, "older_than_max_age": { "type": "integer", "description": "Rows published before the `max_age_days` window." }, "date_unknown": { "type": "integer", "description": "Rows with no publish date, when `max_age_days` was sent." }, "country_not_included": { "type": "integer", "description": "Rows registered to a country that is not in `country`." }, "country_unknown": { "type": "integer", "description": "Rows with no country, when `country` was sent." }, "country_excluded": { "type": "integer", "description": "Rows registered to a country listed in `exclude_country`." } } }, "repeats": { "type": "integer", "description": "Present when you sent `seen`: rows removed because your account already received them under that id." }, "duplicates": { "type": "integer", "description": "Present when above zero: rows a later page repeated from an earlier page of the same walk, kept once." }, "credits": { "type": "object", "description": "What the pages cost.", "properties": { "pages": { "type": "integer", "description": "Credits charged for the pages walked, before refunds." }, "refunded": { "type": "integer", "description": "Credits refunded across the pages." } } }, "request_ids": { "type": "array", "description": "The request id of each page walked. Each is its own entry in `GET /v1/credits/transactions`.", "items": { "type": "string", "description": "A row id." } } } }, "hydration": { "type": "object", "description": "Present when the request asked for a row join with `include=`, or sent a param that implies one. What the join did and what it cost. On a multi-page walk it sums every page. A join that always runs for free is left out.", "properties": { "include": { "type": "string", "description": "The token that switched the join on.", "example": "profile" }, "implied_by": { "type": "string", "description": "Present when you did not send `include` and another param switched the join on. The join's credits (`extra_credits`) are then part of `credits_used`. Absent when you sent `include` yourself." }, "rows": { "type": "integer", "description": "Rows on the page after any row cap.", "example": 20 }, "looked_up": { "type": "integer", "description": "Rows that needed a lookup (at least one field the join fills was empty).", "example": 20 }, "filled": { "type": "integer", "description": "Rows where at least one field was filled by the join.", "example": 18 }, "cached": { "type": "integer", "description": "Of `filled`, rows filled from the sibling endpoint's cache at no charge.", "example": 0 }, "unfilled": { "type": "integer", "description": "Rows that needed a lookup and were not filled (the lookup failed, was skipped, or had nothing to copy). Their credits are refunded.", "example": 2 }, "credits_held": { "type": "integer", "description": "Credits held up front for the join, on top of the page's own price.", "example": 20 }, "extra_credits": { "type": "integer", "description": "Of `credits_held`, the credits kept: one lookup's price for each distinct key filled from a fresh lookup. The rest was refunded.", "example": 18 }, "ms": { "type": "integer", "description": "Time the join added, in milliseconds.", "example": 2400 }, "cached_page": { "type": "boolean", "description": "True when the whole page was served from cache, so the join cost nothing on this call.", "example": true }, "batches": { "type": "integer", "description": "Joins that look rows up in batches only: how many batch calls were made. Absent on a join that looks rows up one by one." }, "from_earlier_pages": { "type": "integer", "description": "`max_pages`, `max_items` and `max_credits` walks only: rows filled free from a key already looked up on an earlier page of the same walk. Not counted in `looked_up`, `filled` or `cached`. Absent when zero." }, "steps": { "type": "array", "description": "Present when the request asked for more than one join (`include=engagement,channel`): one report per join, in the order they ran. The top-level numbers are then the page's: rows looked up or filled by any join, and the credits and time of all of them together.", "items": { "type": "object", "description": "One join's report.", "properties": { "include": { "type": "string", "description": "The token that switched the join on.", "example": "profile" }, "implied_by": { "type": "string", "description": "Present when you did not send `include` and another param switched the join on. The join's credits (`extra_credits`) are then part of `credits_used`. Absent when you sent `include` yourself." }, "rows": { "type": "integer", "description": "Rows on the page after any row cap.", "example": 20 }, "looked_up": { "type": "integer", "description": "Rows that needed a lookup (at least one field the join fills was empty).", "example": 20 }, "filled": { "type": "integer", "description": "Rows where at least one field was filled by the join.", "example": 18 }, "cached": { "type": "integer", "description": "Of `filled`, rows filled from the sibling endpoint's cache at no charge.", "example": 0 }, "unfilled": { "type": "integer", "description": "Rows that needed a lookup and were not filled (the lookup failed, was skipped, or had nothing to copy). Their credits are refunded.", "example": 2 }, "credits_held": { "type": "integer", "description": "Credits held up front for the join, on top of the page's own price.", "example": 20 }, "extra_credits": { "type": "integer", "description": "Of `credits_held`, the credits kept: one lookup's price for each distinct key filled from a fresh lookup. The rest was refunded.", "example": 18 }, "ms": { "type": "integer", "description": "Time the join added, in milliseconds.", "example": 2400 }, "cached_page": { "type": "boolean", "description": "True when the whole page was served from cache, so the join cost nothing on this call.", "example": true }, "batches": { "type": "integer", "description": "Joins that look rows up in batches only: how many batch calls were made. Absent on a join that looks rows up one by one." }, "from_earlier_pages": { "type": "integer", "description": "`max_pages`, `max_items` and `max_credits` walks only: rows filled free from a key already looked up on an earlier page of the same walk. Not counted in `looked_up`, `filled` or `cached`. Absent when zero." } } } } } }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/adlibrary/company/ads", "data": { "items": [ { "post": { "id": "1399070072320010", "url": "https://www.facebook.com/ads/library?id=1399070072320010", "content": { "text": "Sample comment text (redacted).", "media_urls": [ "https://scontent-phl2-1.xx.fbcdn.net/v/t39.35426-6/786819659_1038476302401824_8270588719548095006_n.jpg?_nc_cat=103&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=Lhc-LnjU7cQQ7kNvwHKUXVA&_nc_oc=AdqRNYFQUGx-EWAsCHBB8LcluV92lbFiSFYFiPfqw4Yi_gDP125qAINEtPzJyXjWXiE&_nc_zt=14&_nc_ht=scontent-phl2-1.xx&_nc_gid=Waj4_vFIxluJt9H8p2jwMQ&_nc_ss=78289&oh=00_AQN8uyndemNG1GJ0kgvPcE7zjDo9tJiSm9smqQ3y_PAUbA&oe=6AC5194E", "https://scontent-phl2-1.xx.fbcdn.net/v/t39.35426-6/786854476_886570574308097_7036274883093428982_n.jpg?_nc_cat=102&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=kUR8qcp_p6kQ7kNvwEsnU4-&_nc_oc=AdqAyC95NtSRZ0hj8KTYQuWLrPV14qZMrgOAwf-O5HZgKxkwILuEQLRu38f-t-26gGo&_nc_zt=14&_nc_ht=scontent-phl2-1.xx&_nc_gid=Waj4_vFIxluJt9H8p2jwMQ&_nc_ss=78289&oh=00_AQO_woKW4PbGuyrx2iFiVawQks47vL6WEHN8JvoQB2_6ew&oe=6AC5170F" ], "thumbnail_url": "https://scontent-phl2-1.xx.fbcdn.net/v/t39.35426-6/786819659_1038476302401824_8270588719548095006_n.jpg?_nc_cat=103&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=Lhc-LnjU7cQQ7kNvwHKUXVA&_nc_oc=AdqRNYFQUGx-EWAsCHBB8LcluV92lbFiSFYFiPfqw4Yi_gDP125qAINEtPzJyXjWXiE&_nc_zt=14&_nc_ht=scontent-phl2-1.xx&_nc_gid=Waj4_vFIxluJt9H8p2jwMQ&_nc_ss=78289&oh=00_AQN8uyndemNG1GJ0kgvPcE7zjDo9tJiSm9smqQ3y_PAUbA&oe=6AC5194E", "duration_seconds": null }, "author": { "username": null, "display_name": "Lululemon", "avatar_url": "https://example.com/avatars/user_fc11d1.png", "verified": null }, "engagement": { "views": null, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-08-25T07:00:00.000Z", "ext": { "ad": { "page_id": "33693527731", "currency": "", "spend": null, "reach_estimate": null, "publisher_platforms": [ "FACEBOOK", "INSTAGRAM" ], "categories": [ "UNKNOWN" ], "targeted_or_reached_countries": [], "cta_text": "Learn more", "cta_type": "LEARN_MORE", "link_url": "https://shop.lululemon.com/story/tennis", "is_active": true, "end_date_iso": "2026-10-02T07:00:00.000Z", "display_format": "DCO", "title": "Sample comment text (redacted).", "video_hd_url": "https://video-phl2-1.xx.fbcdn.net/o1/v/t2/f2/m366/AQNaQ8HJi99UmzDxeyJ9srvMA7oZJ4cFGMQoSymK_Zb36AP7oBSkClgxZKA6V6DjIsNgGZnFRIBM8ga0nOzXfKtIKyNRIHy_RZBkKf01dpzs8A.mp4?_nc_cat=111&_nc_sid=b66105&_nc_ht=video-phl2-1.xx.fbcdn.net&_nc_ohc=iRRH5Ce_HVIQ7kNvwEA0w1G&efg=eyJ2ZW5jb2RlX3RhZyI6Inhwdl9wcm9ncmVzc2l2ZS5WSV9VU0VDQVNFX1BST0RVQ1RfVFlQRS4uQzMuMTI4MC5kYXNoX2gyNjQtYmFzaWMtZ2VuMl83MjBwIiwieHB2X2Fzc2V0X2lkIjoxMzcxMzc1ODU1MTQ2MDM4LCJhc3NldF9hZ2VfZGF5cyI6MzgsInZpX3VzZWNhc2VfaWQiOjEwNzk5LCJkdXJhdGlvbl9zIjo1LCJ1cmxnZW5fc291cmNlIjoid3d3In0%3D&ccb=17-1&vs=700353153aa732de&_nc_vs=HBksFQIYRWZiX2VwaGVtZXJhbC9BNjRGODQ4MkE5QTE2N0EyQTA4MkUzOEE3MUNDRjk5Rl9tdF8xX3ZpZGVvX2Rhc2hpbml0Lm1wNBUAAsgBEgAVAhhAZmJfcGVybWFuZW50L0I2NDZDNDlFNEMwNEU3NDU0OUZGNUREODQzMkY4M0FDX2F1ZGlvX2Rhc2hpbml0Lm1wNBUCAsgBEgAoABgAGwKIB3VzZV9vaWwBMRJwcm9ncmVzc2l2ZV9yZWNpcGUBMRUAACbs0JirytDvBBUCKAJDMywXQBfU_fO2RaIYGWRhc2hfaDI2NC1iYXNpYy1nZW4yXzcyMHARAHUAZd6oAQA&_nc_gid=Waj4_vFIxluJt9H8p2jwMQ&_nc_ss=78289&_nc_zt=28&oh=00_AQOO5lzclD2luV5XZEqI96qtXVE3JTjCQv0pUrPaO516lw&oe=6AC54BF5", "video_sd_url": "https://video-phl2-1.xx.fbcdn.net/o1/v/t2/f2/m412/AQPfB7kP_FBMWhe-SC3RJdhnIrE3ebikM4xwZ3d7nPJwmfnCbRzcPwECZWozibfBWZO7vyyc0ALzGxZZ5nQRjT4pBiSX9Yybumj3b19TLQ.mp4?_nc_cat=106&_nc_sid=ef5aa3&_nc_ht=video-phl2-1.xx.fbcdn.net&_nc_ohc=HTdT4raZ3_sQ7kNvwE1A4I-&efg=eyJ2ZW5jb2RlX3RhZyI6Inhwdl9wcm9ncmVzc2l2ZS5WSV9VU0VDQVNFX1BST0RVQ1RfVFlQRS4uQzMuNjQwLnN2ZV9zZCIsInhwdl9hc3NldF9pZCI6MTM3MTM3NTg1NTE0NjAzOCwiYXNzZXRfYWdlX2RheXMiOjM4LCJ2aV91c2VjYXNlX2lkIjoxMDc5OSwiZHVyYXRpb25fcyI6NSwidXJsZ2VuX3NvdXJjZSI6Ind3dyJ9&ccb=17-1&_nc_gid=Waj4_vFIxluJt9H8p2jwMQ&_nc_ss=78289&_nc_zt=28&oh=00_AQNAH46q3sK0IMhvu1VU6bf046-EOP7ogljJBi1bcO1dvA&oe=6AC54850", "page_profile_uri": "https://www.facebook.com/Lululemon/", "page_like_count": 3726250, "page_categories": [ "Clothing (Brand)" ], "caption": "Sample comment text (redacted)." } } }, "computed": { "engagement_rate": null, "language": "fr", "content_category": "other", "estimated_reach": null } }, { "post": { "id": "2216022032553958", "url": "https://www.facebook.com/ads/library?id=2216022032553958", "content": { "text": "Sample comment text (redacted).", "media_urls": [ "https://scontent-phl2-1.xx.fbcdn.net/v/t39.35426-6/786575287_2025888761398156_926178119362647638_n.jpg?_nc_cat=106&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=ox-8YVqmw9AQ7kNvwHVKoR1&_nc_oc=Adq7pUZb-7RLV6sdxMdIkCtI0m0BZKy-5F6LeR_Ft9lcLTmmaPmfB7A3dj2t2GBL8JA&_nc_zt=14&_nc_ht=scontent-phl2-1.xx&_nc_gid=Waj4_vFIxluJt9H8p2jwMQ&_nc_ss=78289&oh=00_AQPnDmZj6-Gax_-ZW9eKVKdMqvaR3Ma4pyj506qMBo_54w&oe=6AC549AE", "https://scontent-phl2-1.xx.fbcdn.net/v/t39.35426-6/786123593_3534708956712135_814860167091400209_n.jpg?_nc_cat=110&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=QLeceaxF9twQ7kNvwEtrINx&_nc_oc=AdrT4hnqmkvvQx6f5CzfiG1VX_DiYs3GCdcLbPQJgHYQSzGkHxEJueGnfwwvQ7oKhsU&_nc_zt=14&_nc_ht=scontent-phl2-1.xx&_nc_gid=Waj4_vFIxluJt9H8p2jwMQ&_nc_ss=78289&oh=00_AQOV2-aUUGd5HbOINebYLdei2-yex_8IupNLQm5aqQMB9A&oe=6AC54429" ], "thumbnail_url": "https://scontent-phl2-1.xx.fbcdn.net/v/t39.35426-6/786575287_2025888761398156_926178119362647638_n.jpg?_nc_cat=106&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=ox-8YVqmw9AQ7kNvwHVKoR1&_nc_oc=Adq7pUZb-7RLV6sdxMdIkCtI0m0BZKy-5F6LeR_Ft9lcLTmmaPmfB7A3dj2t2GBL8JA&_nc_zt=14&_nc_ht=scontent-phl2-1.xx&_nc_gid=Waj4_vFIxluJt9H8p2jwMQ&_nc_ss=78289&oh=00_AQPnDmZj6-Gax_-ZW9eKVKdMqvaR3Ma4pyj506qMBo_54w&oe=6AC549AE", "duration_seconds": null }, "author": { "username": null, "display_name": "Lululemon", "avatar_url": "https://example.com/avatars/user_b21545.png", "verified": null }, "engagement": { "views": null, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-08-25T07:00:00.000Z", "ext": { "ad": { "page_id": "33693527731", "currency": "", "spend": null, "reach_estimate": null, "publisher_platforms": [ "FACEBOOK", "INSTAGRAM" ], "categories": [ "UNKNOWN" ], "targeted_or_reached_countries": [], "cta_text": "Learn more", "cta_type": "LEARN_MORE", "link_url": "https://shop.lululemon.com/story/tennis", "is_active": true, "end_date_iso": "2026-10-01T07:00:00.000Z", "display_format": "DCO", "title": "Sample comment text (redacted).", "video_hd_url": "https://video-phl2-1.xx.fbcdn.net/o1/v/t2/f2/m366/AQPad2vao_ndv0ITX25mAuJ9WBR2lzj_SNEds7-5Dq-Kv-qZW3lLo4xJ2ajjkmEQWPvCewwttqoAKJKcmSu93D3aZQ7GFTQFd0lZbtFPve-Y1Q.mp4?_nc_cat=101&_nc_sid=b66105&_nc_ht=video-phl2-1.xx.fbcdn.net&_nc_ohc=wnsYD-bcd78Q7kNvwFpgrQ1&efg=eyJ2ZW5jb2RlX3RhZyI6Inhwdl9wcm9ncmVzc2l2ZS5WSV9VU0VDQVNFX1BST0RVQ1RfVFlQRS4uQzMuNzIwLmRhc2hfaDI2NC1iYXNpYy1nZW4yXzcyMHAiLCJ4cHZfYXNzZXRfaWQiOjIxOTc5MDUzNjQxMDY5MTAsImFzc2V0X2FnZV9kYXlzIjozOCwidmlfdXNlY2FzZV9pZCI6MTA3OTksImR1cmF0aW9uX3MiOjUsInVybGdlbl9zb3VyY2UiOiJ3d3cifQ%3D%3D&ccb=17-1&vs=dc3f7723db939f9c&_nc_vs=HBksFQIYRWZiX2VwaGVtZXJhbC9BQjQ2REJDNzE4OEQzRjQxQUQwMDg0N0ZDMzk5QkI4Q19tdF8xX3ZpZGVvX2Rhc2hpbml0Lm1wNBUAAsgBEgAVAhhAZmJfcGVybWFuZW50L0NFNDY2NjAxOUNCNzlEMTZDQzhFNTQxNUNEMTJEOEFFX2F1ZGlvX2Rhc2hpbml0Lm1wNBUCAsgBEgAoABgAGwKIB3VzZV9vaWwBMRJwcm9ncmVzc2l2ZV9yZWNpcGUBMRUAACa8-tGH977nBxUCKAJDMywXQBfbItDlYEIYGWRhc2hfaDI2NC1iYXNpYy1nZW4yXzcyMHARAHUAZd6oAQA&_nc_gid=Waj4_vFIxluJt9H8p2jwMQ&_nc_ss=78289&_nc_zt=28&oh=00_AQOUPeNLu57Bx5Jk6NaIBZud4zEv0PvYrgx4banbdLH3tw&oe=6AC5366B", "video_sd_url": "https://video-phl2-1.xx.fbcdn.net/o1/v/t2/f2/m412/AQOSN9gslNEgmOk7dE-3EuqoMdng44jklTyyrJCNuRXJ9aBIcPyFSVN5GdP-uCEIgk27_GL27b67ZNozi6haqEa-vXHfeNj8N4JDSYt7kw.mp4?_nc_cat=104&_nc_sid=ef5aa3&_nc_ht=video-phl2-1.xx.fbcdn.net&_nc_ohc=KIxzpM51gzsQ7kNvwHcCvVJ&efg=eyJ2ZW5jb2RlX3RhZyI6Inhwdl9wcm9ncmVzc2l2ZS5WSV9VU0VDQVNFX1BST0RVQ1RfVFlQRS4uQzMuMzYwLnN2ZV9zZCIsInhwdl9hc3NldF9pZCI6MjE5NzkwNTM2NDEwNjkxMCwiYXNzZXRfYWdlX2RheXMiOjM4LCJ2aV91c2VjYXNlX2lkIjoxMDc5OSwiZHVyYXRpb25fcyI6NSwidXJsZ2VuX3NvdXJjZSI6Ind3dyJ9&ccb=17-1&_nc_gid=Waj4_vFIxluJt9H8p2jwMQ&_nc_ss=78289&_nc_zt=28&oh=00_AQM6xbbyypStObzzEYfgx8AxTeUGVdXhNYObzBt-oSvewQ&oe=6AC514AE", "page_profile_uri": "https://www.facebook.com/Lululemon/", "page_like_count": 3726250, "page_categories": [ "Clothing (brand)" ], "caption": "Sample comment text (redacted)." } } }, "computed": { "engagement_rate": null, "language": "fr", "content_category": "other", "estimated_reach": null } } ], "next_cursor": "AQHT_rrZ7JdG0YQNH7dCNiENAgd53WErhTwMFNpK_KDXsYCfALk5C9uUmWCGc7wlu25d", "total": null, "dropped": 0 }, "credits_used": 5, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiQVFIVF9yclo3SmRHMFlRTkg3ZENOaUVOQWdkNTNXRXJoVHdNRk5wS19LRFhzWUNmQUxrNUM5dVVtV0NHYzd3bHUyNWQiLCJlIjoiZmFjZWJvb2svYWRsaWJyYXJ5L2NvbXBhbnkvYWRzIiwicCI6ImN1cnNvciJ9", "has_more": true, "page_size": 28 }, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/adlibrary/search/ads": { "get": { "summary": "Search Facebook Ad Library", "description": "Searches the Facebook Ad Library for ads matching a keyword. Returns matching ads with creative text, images, sponsor info, and status.", "tags": [ "facebook" ], "operationId": "get_facebook_adlibrary_search_ads", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search keyword or phrase to find ads in the Facebook Ad Library", "schema": { "type": "string" }, "example": "artificial intelligence" }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions.", "schema": { "type": "string", "enum": [ "total_impressions", "relevancy_monthly_grouped" ] } }, { "name": "search_type", "in": "query", "required": false, "description": "If you want to search by exact phrase or not", "schema": { "type": "string", "enum": [ "keyword_unordered", "keyword_exact_phrase" ] } }, { "name": "ad_type", "in": "query", "required": false, "description": "Search for all ads or only political and issue ads", "schema": { "type": "string", "enum": [ "all", "political_and_issue_ads" ] } }, { "name": "country", "in": "query", "required": false, "description": "This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Status of the ad. Defaults to ACTIVE.", "schema": { "type": "string", "enum": [ "ALL", "ACTIVE", "INACTIVE" ] } }, { "name": "media_type", "in": "query", "required": false, "description": "Media type of the ad. Defaults to ALL. Meme just means the ad has text and an image. No clue why they call it meme.", "schema": { "type": "string", "enum": [ "ALL", "IMAGE", "VIDEO", "MEME", "IMAGE_AND_MEME", "NONE" ] } }, { "name": "start_date", "in": "query", "required": false, "description": "Impressions start date. Needs to be in YYYY-MM-DD format.", "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "description": "Impressions end date. Needs to be in YYYY-MM-DD format.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor to paginate through results", "schema": { "type": "string" } }, { "name": "trim", "in": "query", "required": false, "description": "Set to true for a trimmed down version of the response", "schema": { "type": "boolean" } }, { "name": "max_pages", "in": "query", "required": false, "description": "1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "max_items", "in": "query", "required": false, "description": "1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: \"max_items\"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`\"time_budget\"`): send the returned cursor with the same params to continue.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "max_credits", "in": "query", "required": false, "description": "1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: \"max_credits\"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 120 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 120 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/adlibrary/search/ads" }, "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." }, "walk": { "type": "object", "description": "Present when the request sent a row-walk param (`max_pages` above 1, `max_items`, `max_credits`, a row filter, `sort_rows` or `seen`). What the walk did across the pages it fetched. Each page is billed as one call, and its charge is recorded under its own request id.", "properties": { "pages": { "type": "integer", "description": "Pages fetched.", "example": 3 }, "stopped": { "type": "string", "enum": [ "end", "max_pages", "max_items", "max_credits", "time_budget", "page_error" ], "description": "Why the walk stopped. `end`: the list ran out. `max_pages`, `max_items` or `max_credits`: the limit you set was reached. `time_budget`: the request's time budget ran low. `page_error`: a later page failed. Unless it is `end`, `pagination.next_cursor` continues from where the walk stopped.", "example": "max_pages" }, "rows_fetched": { "type": "integer", "description": "Rows read across every page, before any filter.", "example": 60 }, "rows_returned": { "type": "integer", "description": "Rows in `data.items`.", "example": 41 }, "discarded": { "type": "object", "description": "Present when you sent a row filter. Rows the filters removed, counted once each under the first filter they failed. A row a filter cannot verify (no view count, no date, no country) is discarded.", "properties": { "views_below_min": { "type": "integer", "description": "Rows with fewer views than `min_views`." }, "views_unknown": { "type": "integer", "description": "Rows with no view count, when `min_views` was sent." }, "older_than_max_age": { "type": "integer", "description": "Rows published before the `max_age_days` window." }, "date_unknown": { "type": "integer", "description": "Rows with no publish date, when `max_age_days` was sent." }, "country_not_included": { "type": "integer", "description": "Rows registered to a country that is not in `country`." }, "country_unknown": { "type": "integer", "description": "Rows with no country, when `country` was sent." }, "country_excluded": { "type": "integer", "description": "Rows registered to a country listed in `exclude_country`." } } }, "repeats": { "type": "integer", "description": "Present when you sent `seen`: rows removed because your account already received them under that id." }, "duplicates": { "type": "integer", "description": "Present when above zero: rows a later page repeated from an earlier page of the same walk, kept once." }, "credits": { "type": "object", "description": "What the pages cost.", "properties": { "pages": { "type": "integer", "description": "Credits charged for the pages walked, before refunds." }, "refunded": { "type": "integer", "description": "Credits refunded across the pages." } } }, "request_ids": { "type": "array", "description": "The request id of each page walked. Each is its own entry in `GET /v1/credits/transactions`.", "items": { "type": "string", "description": "A row id." } } } }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/adlibrary/search/ads", "data": { "items": [ { "ad_archive_id": "2139784727416787", "collation_count": 3, "collation_id": "3161863597339791", "is_active": true, "page_id": "576808235525866", "page_is_deleted": false, "snapshot": { "branded_content": { "page_id": "576808235525866", "page_is_deleted": false, "page_profile_uri": "https://www.facebook.com/user_b67ec1/", "page_name": "I-Hub IIT Patna Artificial Intelligence and Machine Learning" }, "page_id": "101904016202906", "page_is_deleted": false, "page_profile_uri": "https://www.facebook.com/user_7f99b8/", "root_reshared_post": null, "byline": null, "disclaimer_label": null, "page_name": "High Onn Knowledge", "page_profile_picture_url": "https://scontent-lga3-3.xx.fbcdn.net/v/t39.35426-6/758964133_1751982689261468_2817971388824079048_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=108&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=9GujPrrsoVoQ7kNvwEzBKw3&_nc_oc=AdphdY9dc8BQzCqP4mwtaAr9SYtMfm7zoH66zN4yKfWBTNvc7pVmu_ixehEQFS7kOTQ&_nc_zt=14&_nc_ht=scontent-lga3-3.xx&_nc_gid=vwQxxKvZ9al3_XJcdevFCw&_nc_ss=78289&oh=00_AQM3MSOEkGzujevG2xnS1u5nuBIK87OELHdeRMTdSkZp8Q&oe=6AC52A91", "event": null, "caption": "www.masaischool.com", "cta_text": "Apply now", "cards": [], "body": { "text": "Build strong fundamentals with the AI & Machine Learning Certification Program by Vishlesan i-Hub, IIT Patna. Learn core AI & ML concepts through hands-on projects and practical learning. \n\nClick the link to Apply Now or get the link from my bio" }, "cta_type": "APPLY_NOW", "display_format": "VIDEO", "link_description": null, "link_url": "https://www.masaischool.com/program/iit-patna/ai-ml-sop/accelerate", "images": [], "page_categories": [ "Education website", "Education Service" ], "page_like_count": 86, "title": null, "videos": [ { "video_hd_url": "https://video-lga3-1.xx.fbcdn.net/o1/v/t2/f2/m367/AQMlTgbEWk1bFuhd7FdLhLSeESnhUJiyb9306-Ph3kJgVsqb4LrlWnRv3M1H--g2ymC57qD3k-b3VQIbA2ymTHZziJltjmZ3N1iCFTZBPA.mp4?_nc_cat=111&_nc_sid=ef5aa3&_nc_ht=video-lga3-1.xx.fbcdn.net&_nc_ohc=rjpPzmru7qQQ7kNvwHPotPn&efg=eyJ2ZW5jb2RlX3RhZyI6Inhwdl9wcm9ncmVzc2l2ZS5WSV9VU0VDQVNFX1BST0RVQ1RfVFlQRS4uQzMuNzIwLnByb2dyZXNzaXZlX2gyNjQtYmFzaWMtZ2VuMl83MjBwIiwieHB2X2Fzc2V0X2lkIjoxMDAxMzMzNjUyMzU1MTg4LCJhc3NldF9hZ2VfZGF5cyI6MTI2LCJ2aV91c2VjYXNlX2lkIjoxMjM3NCwiZHVyYXRpb25fcyI6MjgsInVybGdlbl9zb3VyY2UiOiJ3d3cifQ%3D%3D&ccb=17-1&_nc_gid=vwQxxKvZ9al3_XJcdevFCw&_nc_ss=78289&_nc_zt=28&oh=00_AQPFDX9kfbHW6J7II7JEruZ2Tv5INiZJA7KyLg7oAIhF8A&oe=6AC530BF", "video_preview_image_url": "https://example.com/redacted", "video_sd_url": "https://video-lga3-3.xx.fbcdn.net/o1/v/t2/f2/m367/AQOQDi6sUF-QKcYNA2M09_I4Em9Ctdb77on_XXtDkEpFLuqMsjuaP0EkDL7dmYUzYBPNRc_Usk93gUHzqrCB-KdMw2GPRu61sB7LXagv2A.mp4?_nc_cat=104&_nc_sid=ef5aa3&_nc_ht=video-lga3-3.xx.fbcdn.net&_nc_ohc=hm5I4CqeRrwQ7kNvwHpkIDT&efg=eyJ2ZW5jb2RlX3RhZyI6Inhwdl9wcm9ncmVzc2l2ZS5WSV9VU0VDQVNFX1BST0RVQ1RfVFlQRS4uQzMuMzYwLnByb2dyZXNzaXZlX2gyNjQtYmFzaWMtZ2VuMl8zNjBwIiwieHB2X2Fzc2V0X2lkIjoxMDAxMzMzNjUyMzU1MTg4LCJhc3NldF9hZ2VfZGF5cyI6MTI2LCJ2aV91c2VjYXNlX2lkIjoxMjM3NCwiZHVyYXRpb25fcyI6MjgsInVybGdlbl9zb3VyY2UiOiJ3d3cifQ%3D%3D&ccb=17-1&_nc_gid=vwQxxKvZ9al3_XJcdevFCw&_nc_ss=78289&_nc_zt=28&oh=00_AQM0pS8xVx5ZI8zvZng5xRvDMkag2tG22ylsyVpw6HZKoQ&oe=6AC521AA", "watermarked_video_hd_url": null, "watermarked_video_sd_url": null } ], "is_reshared": false, "extra_links": [], "extra_texts": [], "extra_images": [], "extra_videos": [], "country_iso_code": null, "brazil_tax_id": null, "additional_info": null, "ec_certificates": [] }, "has_user_reported": false, "report_count": null, "menu_items": [], "state_media_run_label": null, "page_name": "I-Hub IIT Patna Artificial Intelligence and Machine Learning", "impressions_with_index": { "impressions_text": null, "impressions_index": -1 }, "gated_type": "ELIGIBLE", "categories": [ "UNKNOWN" ], "is_aaa_eligible": false, "contains_digital_created_media": false, "reach_estimate": null, "currency": "", "spend": null, "end_date": 1790838000, "publisher_platform": [ "FACEBOOK", "INSTAGRAM" ], "start_date": 1785308400, "contains_sensitive_content": false, "total_active_time": null, "regional_regulation_data": { "finserv": { "is_deemed_finserv": false, "is_limited_delivery": false }, "tw_anti_scam": { "is_limited_delivery": false } }, "hide_data_status": "NONE", "fev_info": null, "ad_id": null, "targeted_or_reached_countries": [], "url": "https://www.facebook.com/ads/library?id=2139784727416787", "start_date_string": "2026-07-29T07:00:00.000Z", "end_date_string": "2026-10-01T07:00:00.000Z" }, { "ad_archive_id": "1055669670399239", "collation_count": 2, "collation_id": "1383170080575251", "is_active": true, "page_id": "195942257089305", "page_is_deleted": false, "snapshot": { "branded_content": null, "page_id": "195942257089305", "page_is_deleted": false, "page_profile_uri": "https://www.facebook.com/user_8757b4/", "root_reshared_post": null, "byline": null, "disclaimer_label": null, "page_name": "TalentSprint, Part of Accenture", "page_profile_picture_url": "https://scontent-lga3-2.xx.fbcdn.net/v/t39.35426-6/772725939_1960945541196934_8779058005522953830_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=100&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=ttZg0x2EDHwQ7kNvwGERQrn&_nc_oc=AdptUunFqum9jGJ7Q_kOWLhBOQedUL63_LOklzd3dL6SyaERC2gsYl1FOGGz06bxpCc&_nc_zt=14&_nc_ht=scontent-lga3-2.xx&_nc_gid=vwQxxKvZ9al3_XJcdevFCw&_nc_ss=78289&oh=00_AQMOGaKL0SNA1ZoLLKyL00DcLdTMxHtrmQFmv52w0prGuQ&oe=6AC516BE", "event": null, "caption": "galgotiasuniversity.edu.in", "cta_text": "Learn more", "cards": [ { "body": "Looking for a BTech program that goes beyond classroom learning?\n\nIndustry-integrated curriculum, practical projects, future technologies, and career-focused learning designed for tomorrow's engineers.", "cta_type": "LEARN_MORE", "caption": "", "link_description": "Learn beyond the classroom with industry-integrated engineering education.", "link_url": "https://www.galgotiasuniversity.edu.in/industry-integrated-degrees/btech.php?utm_source=fb_webconv&utm_medium=paid_facebook&utm_campaign=gu-fb_webconv-performance-audience-btech-parents&utm_content=gu-fb_webconv-performance-audience-btech-parents", "title": "👉 Not Just a BTech. Build the Future with AI.", "cta_text": "Learn More", "video_hd_url": null, "video_preview_image_url": null, "video_sd_url": null, "watermarked_video_hd_url": null, "watermarked_video_sd_url": null, "image_crops": [], "original_image_url": "https://scontent-lga3-1.xx.fbcdn.net/v/t39.35426-6/772966218_1727642645168960_3218337231393249146_n.jpg?_nc_cat=103&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=5pduJyWHO9QQ7kNvwFsA7sI&_nc_oc=AdpblkfHPX4ONlhj9nimo7AV7aAHCAUU5Ypbs1sFTzyKNBXld0Lve8MX7F2Sx7RdyEA&_nc_zt=14&_nc_ht=scontent-lga3-1.xx&_nc_gid=vwQxxKvZ9al3_XJcdevFCw&_nc_ss=78289&oh=00_AQNak9nfOzxnRTOQUKyhazs--urUcznD8wVwDLDdNBUp5A&oe=6AC52018", "resized_image_url": "https://scontent-lga3-3.xx.fbcdn.net/v/t39.35426-6/772510818_897126909711802_599938382479698218_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=102&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=Ro-KszK899gQ7kNvwGCAB-U&_nc_oc=Adrw5x5arI_dKADNpSWIi4WLL-5LmDZW6Z93KaBbioFph-hXiJaCvh1zh8PYKR9X1o4&_nc_zt=14&_nc_ht=scontent-lga3-3.xx&_nc_gid=vwQxxKvZ9al3_XJcdevFCw&_nc_ss=78289&oh=00_AQPXv35Au7VXFesb42_tkwWVXlmaJYF2Wowbs_ltEhSJ8Q&oe=6AC54AF5", "watermarked_resized_image_url": "" }, { "body": "Looking for a BTech program that goes beyond classroom learning?\n\nIndustry-integrated curriculum, practical projects, future technologies, and career-focused learning designed for tomorrow's engineers.", "cta_type": "LEARN_MORE", "caption": "", "link_description": "Learn beyond the classroom with industry-integrated engineering education.", "link_url": "https://www.galgotiasuniversity.edu.in/industry-integrated-degrees/btech.php?utm_source=fb_webconv&utm_medium=paid_facebook&utm_campaign=gu-fb_webconv-performance-audience-btech-parents&utm_content=gu-fb_webconv-performance-audience-btech-parents", "title": "👉 Not Just a BTech. Build the Future with AI.", "cta_text": "Learn More", "video_hd_url": null, "video_preview_image_url": null, "video_sd_url": null, "watermarked_video_hd_url": null, "watermarked_video_sd_url": null, "image_crops": [], "original_image_url": "https://scontent-lga3-2.xx.fbcdn.net/v/t39.35426-6/772138377_1065149695960474_8145393550861927560_n.jpg?_nc_cat=100&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=WOhY7jjORzsQ7kNvwG-eeUZ&_nc_oc=Adr7JA-3d55aUp0_mQq_zvcHx474KgDCnxnKKvytdRv7ezuRdKdrG2HsjmESVC_uAuM&_nc_zt=14&_nc_ht=scontent-lga3-2.xx&_nc_gid=vwQxxKvZ9al3_XJcdevFCw&_nc_ss=78289&oh=00_AQNnBFKyCEE9sABg_r1anoD4DCqTeWqK8YxXbrzJNJuogw&oe=6AC5175B", "resized_image_url": "https://scontent-lga3-1.xx.fbcdn.net/v/t39.35426-6/772965523_1807113250741448_8419369904608238412_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=109&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=U_-wQB52yMgQ7kNvwG3XfFY&_nc_oc=Ado7NTrzxf9OByha-2xj8GRU5pf40xkOp7VoPYNT4RndkB-Yzh6aoYxZ7bGYuxv2imk&_nc_zt=14&_nc_ht=scontent-lga3-1.xx&_nc_gid=vwQxxKvZ9al3_XJcdevFCw&_nc_ss=78289&oh=00_AQP4Xx_HPel4VXyrhYTRLyRcU3uQwoBeM3szNlgAKrSPyA&oe=6AC54169", "watermarked_resized_image_url": "" } ], "body": { "text": "Looking for a BTech program that goes beyond classroom learning?\n\nIndustry-integrated curriculum, practical projects, future technologies, and career-focused learning designed for tomorrow's engineers." }, "cta_type": "LEARN_MORE", "display_format": "DCO", "link_description": "Learn beyond the classroom with industry-integrated engineering education.", "link_url": "https://www.galgotiasuniversity.edu.in/industry-integrated-degrees/btech.php?utm_source=fb_webconv&utm_medium=paid_facebook&utm_campaign=gu-fb_webconv-performance-audience-btech-parents&utm_content=gu-fb_webconv-performance-audience-btech-parents", "images": [], "page_categories": [ "Education" ], "page_like_count": 639637, "title": "👉 Not Just a BTech. Build the Future with AI.", "videos": [], "is_reshared": false, "extra_links": [], "extra_texts": [], "extra_images": [], "extra_videos": [], "country_iso_code": null, "brazil_tax_id": null, "additional_info": null, "ec_certificates": [] }, "has_user_reported": false, "report_count": null, "menu_items": [], "state_media_run_label": null, "page_name": "TalentSprint, Part of Accenture", "impressions_with_index": { "impressions_text": null, "impressions_index": -1 }, "gated_type": "ELIGIBLE", "categories": [ "UNKNOWN" ], "is_aaa_eligible": false, "contains_digital_created_media": false, "reach_estimate": null, "currency": "", "spend": null, "end_date": 1790838000, "publisher_platform": [ "FACEBOOK", "INSTAGRAM" ], "start_date": 1786518000, "contains_sensitive_content": false, "total_active_time": null, "regional_regulation_data": { "finserv": { "is_deemed_finserv": false, "is_limited_delivery": false }, "tw_anti_scam": { "is_limited_delivery": false } }, "hide_data_status": "NONE", "fev_info": null, "ad_id": null, "targeted_or_reached_countries": [], "url": "https://www.facebook.com/ads/library?id=1055669670399239", "start_date_string": "2026-08-12T07:00:00.000Z", "end_date_string": "2026-10-01T07:00:00.000Z" } ], "next_cursor": "AQHT9bZGmT9QXCGQ5tqS-kL80Awg3MUVy8aPKjLViaCFbDdFyJh34pKRBMcXAOokd9Hv", "dropped": 0 }, "credits_used": 5, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiQVFIVDliWkdtVDlRWENHUTV0cVMta0w4MEF3ZzNNVVZ5OGFQS2pMVmlhQ0ZiRGRGeUpoMzRwS1JCTWNYQU9va2Q5SHYiLCJlIjoiZmFjZWJvb2svYWRsaWJyYXJ5L3NlYXJjaC9hZHMiLCJwIjoiY3Vyc29yIn0", "has_more": true, "page_size": 29 }, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/adlibrary/search/companies": { "get": { "summary": "Search Facebook Ad Library companies", "description": "Searches for companies/pages in the Facebook Ad Library. Returns matching pages with active ad counts and page details.", "tags": [ "facebook" ], "operationId": "get_facebook_adlibrary_search_companies", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search keyword or phrase to find companies in the Facebook Ad Library", "schema": { "type": "string" }, "example": "Nike" }, { "name": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 120 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 120 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/adlibrary/search/companies" }, "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": [ "number", "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": [ "number", "null" ], "description": "Number of accounts followed" }, "posts_count": { "type": [ "number", "null" ], "description": "Total number of posts / videos / tracks / episodes" }, "likes_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at author.ext.employee_count_range.start" }, "end": { "type": [ "number", "null" ], "description": "Numeric at author.ext.employee_count_range.end" } } }, "founded_year": { "type": [ "number", "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": [ "object", "null" ], "description": "Object at author.ext.headquarters" }, "locations": { "type": [ "array", "null" ], "description": "Array at author.ext.locations", "items": { "description": "Leaf at author.ext.locations" } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at author.ext.hashtags", "items": { "description": "Leaf at author.ext.hashtags" } }, "funding": { "type": [ "object", "null" ], "description": "Object 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": [ "number", "null" ], "description": "Numeric at author.ext.rating_count" }, "talking_about_count": { "type": [ "number", "null" ], "description": "Numeric at author.ext.talking_about_count" }, "business_hours": { "type": [ "array", "null" ], "description": "Array at author.ext.business_hours", "items": { "description": "Leaf at author.ext.business_hours" } }, "links": { "type": [ "array", "null" ], "description": "Array at author.ext.links", "items": { "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" ], "enum": [ "app", "web", 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": [ "number", "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": [ "object", "null" ], "description": "Object 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": [ "object", "null" ], "description": "Object at author.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: author.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at author.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at author.ext.localizations.*.description" } } } }, "monthly_listeners": { "type": [ "number", "null" ], "description": "Numeric at author.ext.monthly_listeners" }, "total_ratings": { "type": [ "number", "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": [ "number", "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": "object", "description": "Object at author.ext.rules" } }, "weekly_active_users": { "type": [ "number", "null" ], "description": "Numeric at author.ext.weekly_active_users" }, "weekly_contributions": { "type": [ "number", "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": [ "number", "null" ], "description": "Numeric at author.ext.post_karma" }, "comment_karma": { "type": [ "number", "null" ], "description": "Numeric at author.ext.comment_karma" }, "awardee_karma": { "type": [ "number", "null" ], "description": "Numeric at author.ext.awardee_karma" }, "trophy_count": { "type": [ "number", "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": { "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": [ "object", "null" ], "description": "Object at author.ext.group" }, "search_hit": { "type": [ "object", "null" ], "description": "Nested object: author.ext.search_hit", "properties": { "match": { "type": [ "string", "null" ], "enum": [ "group_page", "post_in_group", "channel_page", "post_in_channel", 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": [ "number", "null" ], "description": "Numeric at author.ext.visitors_today" }, "visitors_total": { "type": [ "number", "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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 } } } } }, "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" } } } } } } }, "/facebook/profile/events": { "get": { "summary": "List a Facebook page's events", "description": "Returns upcoming and past events for a public Facebook page. Each row carries the event title, the permalink, the start time, the host page's name, and on `post.ext.event` the rendered time line (`time_text`, e.g. \"Fri, Sep 11 at 5:00 PM CDT\"), `location_name` (the venue), `city`, `start_timestamp`, and the `is_canceled`, `is_past` and `is_online` flags. `published_at` on this lane is the event's START time, not a publication time, so it is routinely in the FUTURE on an upcoming event. The page's event listing carries no cover image, no description and no RSVP counts, so on a plain call `post.content.thumbnail_url`, `post.engagement.views` and `post.engagement.likes` are null. Send `include=details` and every event is joined, in the same call, to the per-event details lookup: the description, the street address, the coordinates, the hosts (`hosts[]` and the one-line `host_context_text`), the category, the privacy, the attendance count, the cover image and the RSVP counts land on each row. An event has no views or likes, so `engagement.views` then carries the interested count and `engagement.likes` the going count, with the same numbers under their real names on `post.ext.event.interested_count` and `going_count`. Values the row already carried (its shorter time line, its city) are never replaced. Cost: 1 credit for the page plus 1 credit per event filled from a fresh lookup (8 events a page, so 9 credits at most); rows already in cache are filled for free, rows that could not be filled are refunded, and a repeat of the same call within the cache window is 0 credits. Time: `include=details` adds 2 to 6 seconds on a fresh page (the lookups run in parallel and the call waits for the slowest, never more than 12 seconds) and nothing when the rows are already cached. The response carries a `hydration` block itemising rows, lookups, cache hits, credits and milliseconds. Forward the returned cursor for additional pages.", "tags": [ "facebook" ], "operationId": "get_facebook_profile_events", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 9, "x-credit-cost-formula": "1 credit for the page. include=details holds 1 credit per event (8 a page) and keeps only the rows filled from a fresh lookup, so a page is at most 9 credits; rows served from cache are free, unfilled rows 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": "url", "in": "query", "required": true, "description": "Full URL of the public Facebook page.", "schema": { "type": "string" }, "example": "https://www.facebook.com/brickyardoldtown" }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor returned by the previous response for pagination.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Set to `details` (one token only) to fill, on every event in this one call, `post.ext.event.description`, `address`, `latitude`, `longitude`, `hosts`, `host_context_text`, `category`, `privacy`, `attendance_count`, `interested_count` and `going_count`, the cover image on `post.content.thumbnail_url`, and the RSVP counts on `post.engagement.views` (interested) and `.likes` (going). Holds 1 credit per event (8 a page) and keeps only the rows filled from a fresh lookup; rows already in cache and rows the lookup cannot fill are refunded, so a page is never more than 9 credits. The join takes 2 to 6 seconds on a fresh page, never more than 12, and nothing when the rows are already cached; read `data.hydration` for the rows, the credits held and kept, and the time. Without it the call is unchanged.", "schema": { "type": "string", "enum": [ "details" ] } }, { "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": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 600 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 3600 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/profile/events" }, "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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "number", "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": [ "number", "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": [ "number", "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", "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "number", "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; discover reads a country from it into `geo.country` (`source: author_location`). 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": [ "number", "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" }, "link_domain": { "type": [ "string", "null" ], "description": "String at post.ext.link_domain" }, "upvote_ratio": { "type": [ "number", "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" ], "enum": [ "video", "short", "live", "channel", "playlist", 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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "enum": [ "image", "video", "carousel", 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": [ "number", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": { "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": { "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": [ "object", "null" ], "description": "Object 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": { "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/profile/posts`, `/v1/instagram/profile/reels`, `/v1/instagram/search/reels`, `/v1/tiktok/profile/videos` 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": [ "object", "null" ], "description": "Object 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", "enum": [ "image", "video" ], "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "number", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "number", "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": [ "number", "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": [ "object", "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": [ "object", "null" ], "description": "Object at post.ext.retweeted_post" }, "quote_count": { "type": [ "number", "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": { "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": [ "object", "null" ], "description": "Object 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": "object", "description": "Object 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": [ "number", "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": [ "object", "null" ], "description": "Object at post.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: post.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.description" } } } }, "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" ], "enum": [ "minute", "hour", "day", "week", "month", "year", 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": [ "number", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "number", "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": [ "object", "null" ], "description": "Object 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": [ "number", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "object", "null" ], "description": "Object at post.ext.dsp_ids", "additionalProperties": { "type": "string", "description": "String 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": "object", "description": "Object at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "object", "description": "Object at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "object", "description": "Object 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": [ "object", "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": [ "object", "null" ], "description": "Object 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": [ "number", "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": "number", "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": [ "object", "null" ], "description": "Object at post.ext.event" }, "trend": { "type": [ "object", "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" }, "numeric_id": { "type": [ "number", "null" ], "description": "Numeric at post.ext.numeric_id" }, "outbound_url": { "type": [ "string", "null" ], "description": "String at post.ext.outbound_url" }, "group": { "type": [ "object", "null" ], "description": "Object at post.ext.group" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "number", "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": [ "number", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "number", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "number", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "enum": [ "target", "other_named_thing", "generic_word", "not_present" ], "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "number", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "number", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "string", "boolean", "null" ], "description": "Union: number | string | boolean" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } } } } } } }, "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." }, "walk": { "type": "object", "description": "Present when the request sent a row-walk param (`max_pages` above 1, `max_items`, `max_credits`, a row filter, `sort_rows` or `seen`). What the walk did across the pages it fetched. Each page is billed as one call, and its charge is recorded under its own request id.", "properties": { "pages": { "type": "integer", "description": "Pages fetched.", "example": 3 }, "stopped": { "type": "string", "enum": [ "end", "max_pages", "max_items", "max_credits", "time_budget", "page_error" ], "description": "Why the walk stopped. `end`: the list ran out. `max_pages`, `max_items` or `max_credits`: the limit you set was reached. `time_budget`: the request's time budget ran low. `page_error`: a later page failed. Unless it is `end`, `pagination.next_cursor` continues from where the walk stopped.", "example": "max_pages" }, "rows_fetched": { "type": "integer", "description": "Rows read across every page, before any filter.", "example": 60 }, "rows_returned": { "type": "integer", "description": "Rows in `data.items`.", "example": 41 }, "discarded": { "type": "object", "description": "Present when you sent a row filter. Rows the filters removed, counted once each under the first filter they failed. A row a filter cannot verify (no view count, no date, no country) is discarded.", "properties": { "views_below_min": { "type": "integer", "description": "Rows with fewer views than `min_views`." }, "views_unknown": { "type": "integer", "description": "Rows with no view count, when `min_views` was sent." }, "older_than_max_age": { "type": "integer", "description": "Rows published before the `max_age_days` window." }, "date_unknown": { "type": "integer", "description": "Rows with no publish date, when `max_age_days` was sent." }, "country_not_included": { "type": "integer", "description": "Rows registered to a country that is not in `country`." }, "country_unknown": { "type": "integer", "description": "Rows with no country, when `country` was sent." }, "country_excluded": { "type": "integer", "description": "Rows registered to a country listed in `exclude_country`." } } }, "repeats": { "type": "integer", "description": "Present when you sent `seen`: rows removed because your account already received them under that id." }, "duplicates": { "type": "integer", "description": "Present when above zero: rows a later page repeated from an earlier page of the same walk, kept once." }, "credits": { "type": "object", "description": "What the pages cost.", "properties": { "pages": { "type": "integer", "description": "Credits charged for the pages walked, before refunds." }, "refunded": { "type": "integer", "description": "Credits refunded across the pages." } } }, "request_ids": { "type": "array", "description": "The request id of each page walked. Each is its own entry in `GET /v1/credits/transactions`.", "items": { "type": "string", "description": "A row id." } } } }, "hydration": { "type": "object", "description": "Present when the request asked for a row join with `include=`, or sent a param that implies one. What the join did and what it cost. On a multi-page walk it sums every page. A join that always runs for free is left out.", "properties": { "include": { "type": "string", "description": "The token that switched the join on.", "example": "profile" }, "implied_by": { "type": "string", "description": "Present when you did not send `include` and another param switched the join on. The join's credits (`extra_credits`) are then part of `credits_used`. Absent when you sent `include` yourself." }, "rows": { "type": "integer", "description": "Rows on the page after any row cap.", "example": 20 }, "looked_up": { "type": "integer", "description": "Rows that needed a lookup (at least one field the join fills was empty).", "example": 20 }, "filled": { "type": "integer", "description": "Rows where at least one field was filled by the join.", "example": 18 }, "cached": { "type": "integer", "description": "Of `filled`, rows filled from the sibling endpoint's cache at no charge.", "example": 0 }, "unfilled": { "type": "integer", "description": "Rows that needed a lookup and were not filled (the lookup failed, was skipped, or had nothing to copy). Their credits are refunded.", "example": 2 }, "credits_held": { "type": "integer", "description": "Credits held up front for the join, on top of the page's own price.", "example": 20 }, "extra_credits": { "type": "integer", "description": "Of `credits_held`, the credits kept: one lookup's price for each distinct key filled from a fresh lookup. The rest was refunded.", "example": 18 }, "ms": { "type": "integer", "description": "Time the join added, in milliseconds.", "example": 2400 }, "cached_page": { "type": "boolean", "description": "True when the whole page was served from cache, so the join cost nothing on this call.", "example": true }, "batches": { "type": "integer", "description": "Joins that look rows up in batches only: how many batch calls were made. Absent on a join that looks rows up one by one." }, "from_earlier_pages": { "type": "integer", "description": "`max_pages`, `max_items` and `max_credits` walks only: rows filled free from a key already looked up on an earlier page of the same walk. Not counted in `looked_up`, `filled` or `cached`. Absent when zero." }, "steps": { "type": "array", "description": "Present when the request asked for more than one join (`include=engagement,channel`): one report per join, in the order they ran. The top-level numbers are then the page's: rows looked up or filled by any join, and the credits and time of all of them together.", "items": { "type": "object", "description": "One join's report.", "properties": { "include": { "type": "string", "description": "The token that switched the join on.", "example": "profile" }, "implied_by": { "type": "string", "description": "Present when you did not send `include` and another param switched the join on. The join's credits (`extra_credits`) are then part of `credits_used`. Absent when you sent `include` yourself." }, "rows": { "type": "integer", "description": "Rows on the page after any row cap.", "example": 20 }, "looked_up": { "type": "integer", "description": "Rows that needed a lookup (at least one field the join fills was empty).", "example": 20 }, "filled": { "type": "integer", "description": "Rows where at least one field was filled by the join.", "example": 18 }, "cached": { "type": "integer", "description": "Of `filled`, rows filled from the sibling endpoint's cache at no charge.", "example": 0 }, "unfilled": { "type": "integer", "description": "Rows that needed a lookup and were not filled (the lookup failed, was skipped, or had nothing to copy). Their credits are refunded.", "example": 2 }, "credits_held": { "type": "integer", "description": "Credits held up front for the join, on top of the page's own price.", "example": 20 }, "extra_credits": { "type": "integer", "description": "Of `credits_held`, the credits kept: one lookup's price for each distinct key filled from a fresh lookup. The rest was refunded.", "example": 18 }, "ms": { "type": "integer", "description": "Time the join added, in milliseconds.", "example": 2400 }, "cached_page": { "type": "boolean", "description": "True when the whole page was served from cache, so the join cost nothing on this call.", "example": true }, "batches": { "type": "integer", "description": "Joins that look rows up in batches only: how many batch calls were made. Absent on a join that looks rows up one by one." }, "from_earlier_pages": { "type": "integer", "description": "`max_pages`, `max_items` and `max_credits` walks only: rows filled free from a key already looked up on an earlier page of the same walk. Not counted in `looked_up`, `filled` or `cached`. Absent when zero." } } } } } }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/profile/events", "data": { "items": [ { "post": { "id": "1824704508673350", "url": "https://www.facebook.com/events/1824704508673350/", "content": { "text": "Sample comment text (redacted).", "media_urls": null, "thumbnail_url": null, "duration_seconds": null }, "author": { "username": null, "display_name": "user_d8b6c8", "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": "2026-10-02T22:30:00.000Z", "ext": { "author_id": "user_31473f", "published_at_epoch": 1790980200, "event": { "time_text": "Fri, Oct 2 at 5:30 PM CDT", "is_canceled": false, "is_past": false, "is_online": false, "location_name": "Brickyard", "city": "Wichita", "start_timestamp": 1790980200 } } }, "computed": { "engagement_rate": null, "language": null, "content_category": "other", "estimated_reach": null } }, { "post": { "id": "2442231312923237", "url": "https://www.facebook.com/events/2442231312923237/", "content": { "text": "Sample comment text (redacted).", "media_urls": null, "thumbnail_url": null, "duration_seconds": null }, "author": { "username": null, "display_name": "user_d8b6c8", "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": "2026-10-03T01:00:00.000Z", "ext": { "author_id": "user_31473f", "published_at_epoch": 1790989200, "event": { "time_text": "Fri, Oct 2 at 8:00 PM CDT", "is_canceled": false, "is_past": false, "is_online": false, "location_name": "Brickyard", "city": "Wichita", "start_timestamp": 1790989200 } } }, "computed": { "engagement_rate": null, "language": null, "content_category": "other", "estimated_reach": null } } ], "next_cursor": "eyJpZCI6IllYQndYMk52Ykd4bFkzUnBiMjQ2Y0daaWFXUXdNak51YnpVeldrZFJOVXM0UWtaVk5UUklhRmg2TVZwbU5FSlhNa3RNVUhCTmFtVnhaMkZGU2xsVVpYaElTa2czVlVob01YZFFaWFpUTjFCSVFsUTBOakZ5VUhKd04xZzNUVkY1WWpSRU0wZEZWbk5uT1haRWVXdFpVMFV6UVZOcyIsImN1cnNvciI6IkFRSFQ4cUtoRjJDTnVjY3FiVmJONTk0NFY5XzNTQ1Rud0NNX1o0NmVNeXl3eWJ0eTcxY3ZHS0dWclA5LVdDUGt6QS04ckhhZXI1QTdxYUZHTktWOXg5WGlqUSJ9", "total": 11, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiZXlKcFpDSTZJbGxZUW5kWU1rNTJZa2Q0YkZrelVuQmlNalEyWTBkYWFXRlhVWGROYWs1MVlucFZlbGRyWkZKT1ZYTTBVV3RhVms1VVVrbGhSbWcyVFZad2JVNUZTbGhOYTNSTlZVaENUbUZ0Vm5oYU1rWkdVMnhzVlZwWWFFbFRhMmN6VmxWb2IwMVlaRkZhV0ZwVVRqRkNTVkZzVVRCT2FrWjVWVWhLZDA0eFp6TlVWa1kxV1dwU1JVMHdaRVpXYms1dVQxaGFSV1ZYZEZwVk1GVjZVVlpPY3lJc0ltTjFjbk52Y2lJNklrRlJTRlE0Y1V0b1JqSkRUblZqWTNGaVZtSk9OVGswTkZZNVh6TlRRMVJ1ZDBOTlgxbzBObVZOZVhsM2VXSjBlVGN4WTNaSFMwZFdjbEE1TFZkRFVHdDZRUzA0Y2toaFpYSTFRVGR4WVVaSFRrdFdPWGc1V0dscVVTSjkiLCJlIjoiZmFjZWJvb2svcHJvZmlsZS9ldmVudHMiLCJwIjoiY3Vyc29yIn0", "has_more": true, "page_size": 8 }, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/post/comment/replies": { "get": { "summary": "List replies to a Facebook post comment", "description": "Returns the reply thread for a single Facebook comment. Both `feedback_id` and `expansion_token` come from the parent `/v1/facebook/post/comments` response: note that `feedback_id` is NOT the comment ID. Forward the returned cursor for additional pages. Each reply carries `comment.parent_id`, the `comment.id` of the comment it answers. An `expansion_token` belongs to its comment and must be passed whole (a complete token is about 750 characters). Tokens two and a half days old still return their replies; an expired or incomplete token returns an empty list, the same answer as a comment whose replies are all hidden, so every empty page carries a `stale_expansion_token` note in `_warnings` with the token's issue time and length. Read the comment again from `/v1/facebook/post/comments` for a fresh token.", "tags": [ "facebook" ], "operationId": "get_facebook_post_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": "feedback_id", "in": "query", "required": true, "description": "`feedback_id` from `/v1/facebook/post/comments` for the parent comment (this is NOT the comment ID).", "schema": { "type": "string" }, "example": "ZmVlZGJhY2s6MzM3MzYxMzI5OTQ4Nzc1NV8xOTI5NTk0OTE3Njg3MTcz" }, { "name": "expansion_token", "in": "query", "required": true, "description": "`expansion_token` from `/v1/facebook/post/comments` for the parent comment.", "schema": { "type": "string" }, "example": "MjoxNzc4NjM1MDM3OgF_JaMa3kMP9RIWC" }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor returned by the previous response for pagination.", "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 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": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 300 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 300 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/post/comment/replies" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical comment wrappers ({ comment, computed })", "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": [ "number", "null" ], "description": "Like / upvote count" }, "replies": { "type": [ "number", "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", "number", "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": [ "number", "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": [ "number", "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": { "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": { "description": "Leaf at comment.ext.preview_replies" } }, "lookup": { "type": [ "object", "null" ], "description": "Object 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": [ "number", "null" ], "description": "Numeric at comment.ext.subreddit_subscribers" }, "post_score": { "type": [ "number", "null" ], "description": "Numeric at comment.ext.post_score" }, "post_comment_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "The commenter's following count as embedded in this row. Same snapshot caveat as `author_followers`." }, "author_posts_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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`." } } } }, "computed": { "type": "object", "description": "Server-computed fields for this comment", "properties": { "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the comment text, or the platform's own label when it publishes one. Null when undetectable." }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "null" ], "description": "Numeric at computed.labels.*.*" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } } } } } } }, "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." }, "labels": { "type": "object", "description": "Present when the page's rows were put through labelling: the default labels on a list that carries them, and any labels you named with `label=`. Absent with `judgments=off`. Reports what was judged, what is still pending and what it cost.", "properties": { "presets": { "type": "array", "description": "The labels this report covers.", "items": { "type": "string", "description": "A label name.", "example": "sentiment" } }, "rows": { "type": "integer", "description": "Rows on the page before any drop.", "example": 50 }, "labelled": { "type": "integer", "description": "Rows that carry every label this report covers, freshly judged or from the shared store.", "example": 50 }, "cached": { "type": "integer", "description": "Of `labelled`, rows served entirely from the shared per-row label store.", "example": 0 }, "skipped": { "type": "integer", "description": "Deleted or empty rows. They are never sent for judging or billed and carry `labels: null`.", "example": 0 }, "unjudged": { "type": "integer", "description": "Rows that could not be judged this time (a failure, or past the number of rows one call judges). They carry `labels: null` and are never billed.", "example": 0 }, "dropped": { "type": "integer", "description": "Rows removed by an `exclude=` you asked for. Default labels never drop a row.", "example": 0 }, "dropped_ids": { "type": "array", "description": "Ids of the rows counted in `dropped`.", "items": { "type": "string", "description": "A row id." } }, "extra_credits": { "type": "integer", "description": "Credits the labels added to this call. Always 0 for the default labels.", "example": 0 }, "methodology_version": { "type": "string", "description": "The version of the label questions, so you can tell when they change.", "example": "labels/1" }, "mode": { "type": "string", "enum": [ "default", "requested" ], "description": "`default` when you sent no `label=` and the free default labels ran, `requested` when you named labels.", "example": "default" }, "status": { "type": "string", "enum": [ "complete", "partial", "skipped" ], "description": "`complete`: every judgeable row carries its labels. `partial`: some rows carry `labels: null`, still being judged (see `pending`) or not judged this time. `skipped`: default judging was switched off for this request by a capacity guard, and the page is exactly as it was before labels existed.", "example": "complete" }, "pending": { "type": "integer", "description": "Default labels only: rows still being judged when the page was sent. They ship with `labels: null`, keep being judged afterwards, and your next call for the same page carries them.", "example": 0 }, "pending_ids": { "type": "array", "description": "Ids of the rows counted in `pending`.", "items": { "type": "string", "description": "A row id." } }, "cached_page": { "type": "boolean", "description": "Present and true when the whole page came from the response cache, so this call judged nothing and charged nothing.", "example": true }, "default": { "type": "object", "description": "Present when you named some labels with `label=`: the report of the default labels you did not name, with its own `mode`, `status`, `pending` and `pending_ids`. Absent when you named every default.", "properties": { "presets": { "type": "array", "description": "The labels this report covers.", "items": { "type": "string", "description": "A label name.", "example": "sentiment" } }, "rows": { "type": "integer", "description": "Rows on the page before any drop.", "example": 50 }, "labelled": { "type": "integer", "description": "Rows that carry every label this report covers, freshly judged or from the shared store.", "example": 50 }, "cached": { "type": "integer", "description": "Of `labelled`, rows served entirely from the shared per-row label store.", "example": 0 }, "skipped": { "type": "integer", "description": "Deleted or empty rows. They are never sent for judging or billed and carry `labels: null`.", "example": 0 }, "unjudged": { "type": "integer", "description": "Rows that could not be judged this time (a failure, or past the number of rows one call judges). They carry `labels: null` and are never billed.", "example": 0 }, "dropped": { "type": "integer", "description": "Rows removed by an `exclude=` you asked for. Default labels never drop a row.", "example": 0 }, "dropped_ids": { "type": "array", "description": "Ids of the rows counted in `dropped`.", "items": { "type": "string", "description": "A row id." } }, "extra_credits": { "type": "integer", "description": "Credits the labels added to this call. Always 0 for the default labels.", "example": 0 }, "methodology_version": { "type": "string", "description": "The version of the label questions, so you can tell when they change.", "example": "labels/1" }, "mode": { "type": "string", "enum": [ "default", "requested" ], "description": "`default` when you sent no `label=` and the free default labels ran, `requested` when you named labels.", "example": "default" }, "status": { "type": "string", "enum": [ "complete", "partial", "skipped" ], "description": "`complete`: every judgeable row carries its labels. `partial`: some rows carry `labels: null`, still being judged (see `pending`) or not judged this time. `skipped`: default judging was switched off for this request by a capacity guard, and the page is exactly as it was before labels existed.", "example": "complete" }, "pending": { "type": "integer", "description": "Default labels only: rows still being judged when the page was sent. They ship with `labels: null`, keep being judged afterwards, and your next call for the same page carries them.", "example": 0 }, "pending_ids": { "type": "array", "description": "Ids of the rows counted in `pending`.", "items": { "type": "string", "description": "A row id." } }, "cached_page": { "type": "boolean", "description": "Present and true when the whole page came from the response cache, so this call judged nothing and charged nothing.", "example": true } } } } }, "label_share": { "type": "object", "description": "Present on a comment list that carries labels. What share of the page's comments are questions, show purchase intent, complain, or are positive, neutral or negative, each with a 90% confidence interval and up to three verbatim receipts. Counted from the labels already on the page's rows; nothing is dropped or reordered, and it costs nothing.", "properties": { "policy_version": { "type": "string", "description": "The version of the cuts used.", "example": "share/1" }, "presets": { "type": "object", "description": "One share per label.", "properties": { "question": { "type": "object", "description": "One label's share of the page, with the evidence behind it.", "properties": { "n": { "type": "integer", "description": "Rows considered.", "example": 50 }, "counted": { "type": "integer", "description": "Rows that counted toward the share.", "example": 12 }, "abstained": { "type": "integer", "description": "Rows left out of the share because the judgment was too uncertain or could not be made. They still count in `n`.", "example": 4 }, "share": { "type": [ "number", "null" ], "description": "`counted` divided by the rows that were decided (`n` minus `abstained`), from 0 to 1. Null when `too_few` is true, because the interval is too wide to publish a headline number.", "example": 0.26 }, "low": { "type": [ "number", "null" ], "description": "Lower end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.16 }, "high": { "type": [ "number", "null" ], "description": "Upper end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.39 }, "receipts": { "type": "array", "description": "Up to three rows that counted, with their text copied unchanged.", "items": { "type": "object", "description": "One verbatim receipt: a row that counted toward the share.", "properties": { "id": { "type": "string", "description": "The row's id." }, "text": { "type": "string", "description": "The row's text, copied unchanged." } } } }, "policy_version": { "type": "string", "description": "The version of the rules that set the cut, so you can tell when they change.", "example": "share/1" }, "too_few": { "type": "boolean", "description": "True when there are too few decided rows for the interval to be narrow enough to publish `share`.", "example": false }, "at_cut": { "type": "integer", "description": "Rows whose probability is at or above the documented 0.5 cut, weak yeses included.", "example": 14 }, "nulls": { "type": "integer", "description": "Rows that carry no value for this label (not judged, or deleted).", "example": 0 }, "low_confidence": { "type": "integer", "description": "Rows whose answer sat too close to the cut to count toward the share.", "example": 3 } } }, "purchase_intent": { "type": "object", "description": "One label's share of the page, with the evidence behind it.", "properties": { "n": { "type": "integer", "description": "Rows considered.", "example": 50 }, "counted": { "type": "integer", "description": "Rows that counted toward the share.", "example": 12 }, "abstained": { "type": "integer", "description": "Rows left out of the share because the judgment was too uncertain or could not be made. They still count in `n`.", "example": 4 }, "share": { "type": [ "number", "null" ], "description": "`counted` divided by the rows that were decided (`n` minus `abstained`), from 0 to 1. Null when `too_few` is true, because the interval is too wide to publish a headline number.", "example": 0.26 }, "low": { "type": [ "number", "null" ], "description": "Lower end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.16 }, "high": { "type": [ "number", "null" ], "description": "Upper end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.39 }, "receipts": { "type": "array", "description": "Up to three rows that counted, with their text copied unchanged.", "items": { "type": "object", "description": "One verbatim receipt: a row that counted toward the share.", "properties": { "id": { "type": "string", "description": "The row's id." }, "text": { "type": "string", "description": "The row's text, copied unchanged." } } } }, "policy_version": { "type": "string", "description": "The version of the rules that set the cut, so you can tell when they change.", "example": "share/1" }, "too_few": { "type": "boolean", "description": "True when there are too few decided rows for the interval to be narrow enough to publish `share`.", "example": false }, "at_cut": { "type": "integer", "description": "Rows whose probability is at or above the documented 0.5 cut, weak yeses included.", "example": 14 }, "nulls": { "type": "integer", "description": "Rows that carry no value for this label (not judged, or deleted).", "example": 0 }, "low_confidence": { "type": "integer", "description": "Rows whose answer sat too close to the cut to count toward the share.", "example": 3 } } }, "complaint": { "type": "object", "description": "One label's share of the page, with the evidence behind it.", "properties": { "n": { "type": "integer", "description": "Rows considered.", "example": 50 }, "counted": { "type": "integer", "description": "Rows that counted toward the share.", "example": 12 }, "abstained": { "type": "integer", "description": "Rows left out of the share because the judgment was too uncertain or could not be made. They still count in `n`.", "example": 4 }, "share": { "type": [ "number", "null" ], "description": "`counted` divided by the rows that were decided (`n` minus `abstained`), from 0 to 1. Null when `too_few` is true, because the interval is too wide to publish a headline number.", "example": 0.26 }, "low": { "type": [ "number", "null" ], "description": "Lower end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.16 }, "high": { "type": [ "number", "null" ], "description": "Upper end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.39 }, "receipts": { "type": "array", "description": "Up to three rows that counted, with their text copied unchanged.", "items": { "type": "object", "description": "One verbatim receipt: a row that counted toward the share.", "properties": { "id": { "type": "string", "description": "The row's id." }, "text": { "type": "string", "description": "The row's text, copied unchanged." } } } }, "policy_version": { "type": "string", "description": "The version of the rules that set the cut, so you can tell when they change.", "example": "share/1" }, "too_few": { "type": "boolean", "description": "True when there are too few decided rows for the interval to be narrow enough to publish `share`.", "example": false }, "at_cut": { "type": "integer", "description": "Rows whose probability is at or above the documented 0.5 cut, weak yeses included.", "example": 14 }, "nulls": { "type": "integer", "description": "Rows that carry no value for this label (not judged, or deleted).", "example": 0 }, "low_confidence": { "type": "integer", "description": "Rows whose answer sat too close to the cut to count toward the share.", "example": 3 } } }, "sentiment": { "type": "object", "description": "Sentiment, split into three bands.", "properties": { "positive": { "type": "object", "description": "One label's share of the page, with the evidence behind it.", "properties": { "n": { "type": "integer", "description": "Rows considered.", "example": 50 }, "counted": { "type": "integer", "description": "Rows that counted toward the share.", "example": 12 }, "abstained": { "type": "integer", "description": "Rows left out of the share because the judgment was too uncertain or could not be made. They still count in `n`.", "example": 4 }, "share": { "type": [ "number", "null" ], "description": "`counted` divided by the rows that were decided (`n` minus `abstained`), from 0 to 1. Null when `too_few` is true, because the interval is too wide to publish a headline number.", "example": 0.26 }, "low": { "type": [ "number", "null" ], "description": "Lower end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.16 }, "high": { "type": [ "number", "null" ], "description": "Upper end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.39 }, "receipts": { "type": "array", "description": "Up to three rows that counted, with their text copied unchanged.", "items": { "type": "object", "description": "One verbatim receipt: a row that counted toward the share.", "properties": { "id": { "type": "string", "description": "The row's id." }, "text": { "type": "string", "description": "The row's text, copied unchanged." } } } }, "policy_version": { "type": "string", "description": "The version of the rules that set the cut, so you can tell when they change.", "example": "share/1" }, "too_few": { "type": "boolean", "description": "True when there are too few decided rows for the interval to be narrow enough to publish `share`.", "example": false }, "at_cut": { "type": "integer", "description": "Rows whose probability is at or above the documented 0.5 cut, weak yeses included.", "example": 14 }, "nulls": { "type": "integer", "description": "Rows that carry no value for this label (not judged, or deleted).", "example": 0 }, "low_confidence": { "type": "integer", "description": "Rows whose answer sat too close to the cut to count toward the share.", "example": 3 } } }, "neutral": { "type": "object", "description": "One label's share of the page, with the evidence behind it.", "properties": { "n": { "type": "integer", "description": "Rows considered.", "example": 50 }, "counted": { "type": "integer", "description": "Rows that counted toward the share.", "example": 12 }, "abstained": { "type": "integer", "description": "Rows left out of the share because the judgment was too uncertain or could not be made. They still count in `n`.", "example": 4 }, "share": { "type": [ "number", "null" ], "description": "`counted` divided by the rows that were decided (`n` minus `abstained`), from 0 to 1. Null when `too_few` is true, because the interval is too wide to publish a headline number.", "example": 0.26 }, "low": { "type": [ "number", "null" ], "description": "Lower end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.16 }, "high": { "type": [ "number", "null" ], "description": "Upper end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.39 }, "receipts": { "type": "array", "description": "Up to three rows that counted, with their text copied unchanged.", "items": { "type": "object", "description": "One verbatim receipt: a row that counted toward the share.", "properties": { "id": { "type": "string", "description": "The row's id." }, "text": { "type": "string", "description": "The row's text, copied unchanged." } } } }, "policy_version": { "type": "string", "description": "The version of the rules that set the cut, so you can tell when they change.", "example": "share/1" }, "too_few": { "type": "boolean", "description": "True when there are too few decided rows for the interval to be narrow enough to publish `share`.", "example": false }, "at_cut": { "type": "integer", "description": "Rows whose probability is at or above the documented 0.5 cut, weak yeses included.", "example": 14 }, "nulls": { "type": "integer", "description": "Rows that carry no value for this label (not judged, or deleted).", "example": 0 }, "low_confidence": { "type": "integer", "description": "Rows whose answer sat too close to the cut to count toward the share.", "example": 3 } } }, "negative": { "type": "object", "description": "One label's share of the page, with the evidence behind it.", "properties": { "n": { "type": "integer", "description": "Rows considered.", "example": 50 }, "counted": { "type": "integer", "description": "Rows that counted toward the share.", "example": 12 }, "abstained": { "type": "integer", "description": "Rows left out of the share because the judgment was too uncertain or could not be made. They still count in `n`.", "example": 4 }, "share": { "type": [ "number", "null" ], "description": "`counted` divided by the rows that were decided (`n` minus `abstained`), from 0 to 1. Null when `too_few` is true, because the interval is too wide to publish a headline number.", "example": 0.26 }, "low": { "type": [ "number", "null" ], "description": "Lower end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.16 }, "high": { "type": [ "number", "null" ], "description": "Upper end of the 90% confidence interval around `share`, or null when no row was decided.", "example": 0.39 }, "receipts": { "type": "array", "description": "Up to three rows that counted, with their text copied unchanged.", "items": { "type": "object", "description": "One verbatim receipt: a row that counted toward the share.", "properties": { "id": { "type": "string", "description": "The row's id." }, "text": { "type": "string", "description": "The row's text, copied unchanged." } } } }, "policy_version": { "type": "string", "description": "The version of the rules that set the cut, so you can tell when they change.", "example": "share/1" }, "too_few": { "type": "boolean", "description": "True when there are too few decided rows for the interval to be narrow enough to publish `share`.", "example": false }, "at_cut": { "type": "integer", "description": "Rows whose probability is at or above the documented 0.5 cut, weak yeses included.", "example": 14 }, "nulls": { "type": "integer", "description": "Rows that carry no value for this label (not judged, or deleted).", "example": 0 }, "low_confidence": { "type": "integer", "description": "Rows whose answer sat too close to the cut to count toward the share.", "example": 3 } } } } } } } } }, "comment_language": { "type": "object", "description": "Present on a comment list that carries labels. The mix of languages the page's commenters write in. It describes the comments, not a country.", "properties": { "policy_version": { "type": "string", "description": "The version of the cuts used.", "example": "share/1" }, "n": { "type": "integer", "description": "Comments considered.", "example": 50 }, "abstained": { "type": "integer", "description": "Comments left out because the language could not be told (emoji, a handle, a single word).", "example": 6 }, "judged_by": { "type": "object", "description": "How each comment's language was settled.", "properties": { "script": { "type": "integer", "description": "Comments settled from their writing system (Hangul, Kana, Thai and so on)." }, "detector": { "type": "integer", "description": "Comments settled from the row's own `computed.language`." }, "choice": { "type": "integer", "description": "Latin-script comments settled by a judged choice from a closed list of languages." } } }, "shares": { "type": "object", "description": "One share per language that was counted, keyed by language code (for example `en`, `ko`). Each value has `n`, `counted`, `abstained`, `share`, `low`, `high`, `receipts`, `policy_version` and `too_few`, as in `label_share`." } } }, "comment_recency": { "type": "object", "description": "Present on every comment list. How alive the thread is, from the comments on this page and the post's age. Rows are not dropped or reordered.", "properties": { "policy_version": { "type": "string", "description": "The version of the cuts used.", "example": "d09-1" }, "n": { "type": "integer", "description": "Comments considered, replies included.", "example": 50 }, "counted": { "type": "integer", "description": "Comments with a usable date.", "example": 50 }, "abstained": { "type": "integer", "description": "Comments with no usable date.", "example": 0 }, "share_last_24h": { "type": [ "number", "null" ], "description": "Share of dated comments written in the last 24 hours, from 0 to 1. A floor when `recent_share_is_floor` is true.", "example": 0.22 }, "share_later_half": { "type": [ "number", "null" ], "description": "Share of dated comments written in the later half of the post's life so far. Null when the post's date is unknown.", "example": 0.6 }, "too_few": { "type": "boolean", "description": "True when fewer than 8 comments are dated, so `stage` is `unknown`.", "example": false }, "stage": { "type": "string", "enum": [ "alive", "slowing", "spent", "too_young", "unknown" ], "description": "`alive`: comments are still arriving. `slowing`: fewer are arriving. `spent`: the thread has gone quiet. `too_young`: the post is under a day old. `unknown`: too few dated comments to say.", "example": "alive" }, "order": { "type": "string", "enum": [ "recent", "top", "default" ], "description": "The order this page was read in.", "example": "recent" }, "recent_share_is_floor": { "type": "boolean", "description": "True when the page was not read newest first, so newer comments may sit on a page you did not read and `share_last_24h` is at least this value.", "example": false }, "receipts": { "type": "array", "description": "Up to three of the newest comments from the last 24 hours, with their text copied unchanged.", "items": { "type": "object", "description": "One verbatim receipt: a row that counted toward the share.", "properties": { "id": { "type": "string", "description": "The row's id." }, "text": { "type": "string", "description": "The row's text, copied unchanged." } } } } } }, "walk": { "type": "object", "description": "Present when the request sent a row-walk param (`max_pages` above 1, `max_items`, `max_credits`, a row filter, `sort_rows` or `seen`). What the walk did across the pages it fetched. Each page is billed as one call, and its charge is recorded under its own request id.", "properties": { "pages": { "type": "integer", "description": "Pages fetched.", "example": 3 }, "stopped": { "type": "string", "enum": [ "end", "max_pages", "max_items", "max_credits", "time_budget", "page_error" ], "description": "Why the walk stopped. `end`: the list ran out. `max_pages`, `max_items` or `max_credits`: the limit you set was reached. `time_budget`: the request's time budget ran low. `page_error`: a later page failed. Unless it is `end`, `pagination.next_cursor` continues from where the walk stopped.", "example": "max_pages" }, "rows_fetched": { "type": "integer", "description": "Rows read across every page, before any filter.", "example": 60 }, "rows_returned": { "type": "integer", "description": "Rows in `data.items`.", "example": 41 }, "discarded": { "type": "object", "description": "Present when you sent a row filter. Rows the filters removed, counted once each under the first filter they failed. A row a filter cannot verify (no view count, no date, no country) is discarded.", "properties": { "views_below_min": { "type": "integer", "description": "Rows with fewer views than `min_views`." }, "views_unknown": { "type": "integer", "description": "Rows with no view count, when `min_views` was sent." }, "older_than_max_age": { "type": "integer", "description": "Rows published before the `max_age_days` window." }, "date_unknown": { "type": "integer", "description": "Rows with no publish date, when `max_age_days` was sent." }, "country_not_included": { "type": "integer", "description": "Rows registered to a country that is not in `country`." }, "country_unknown": { "type": "integer", "description": "Rows with no country, when `country` was sent." }, "country_excluded": { "type": "integer", "description": "Rows registered to a country listed in `exclude_country`." } } }, "repeats": { "type": "integer", "description": "Present when you sent `seen`: rows removed because your account already received them under that id." }, "duplicates": { "type": "integer", "description": "Present when above zero: rows a later page repeated from an earlier page of the same walk, kept once." }, "credits": { "type": "object", "description": "What the pages cost.", "properties": { "pages": { "type": "integer", "description": "Credits charged for the pages walked, before refunds." }, "refunded": { "type": "integer", "description": "Credits refunded across the pages." } } }, "request_ids": { "type": "array", "description": "The request id of each page walked. Each is its own entry in `GET /v1/credits/transactions`.", "items": { "type": "string", "description": "A row id." } } } }, "estimate": { "type": "object", "description": "Present only on a dry run (`dry_run=1`). A dry run charges 0 credits, fetches nothing and returns `data.valid`, `data.normalized_params` and this `estimate` in place of the usual rows. An invalid request is the normal free 400 instead.", "properties": { "kind": { "type": "string", "description": "Always `estimate`.", "example": "estimate" }, "version": { "type": "integer", "description": "The version of this estimate shape.", "example": 1 }, "id": { "type": "string", "description": "The endpoint, as `platform/resource`." }, "method": { "type": "string", "description": "The HTTP method.", "example": "GET" }, "valid": { "type": "boolean", "description": "True when the request would pass every check made before billing.", "example": true }, "hold": { "type": "integer", "description": "Exactly what the router would deduct up front for this request." }, "expected_min": { "type": "integer", "description": "The least a successful call settles at." }, "expected_max": { "type": "integer", "description": "The most a call can settle at. Unused hold is refunded." }, "unit": { "type": "string", "description": "Always `credits`.", "example": "credits" }, "pricing": { "type": "string", "enum": [ "flat", "metered" ], "description": "`flat`: the same price every call. `metered`: the price depends on the work done, and unused hold is refunded.", "example": "flat" }, "formula": { "type": "string", "description": "How the price is worked out, in words." }, "levers": { "type": "array", "description": "Params that change the price, each with the hold for the same request with that one change.", "items": { "type": "object", "description": "One lever.", "properties": { "param": { "type": "string", "description": "The param to change." }, "hold": { "type": "integer", "description": "The hold for the same request with this one change." }, "effect": { "type": "string", "description": "What the change does." } } } }, "cached_likely": { "type": "boolean", "description": "Always false: a dry run does not read the cache.", "example": false }, "normalized_params": { "type": "object", "description": "The params the router prices, after its own normalisation." }, "notes": { "type": "array", "description": "Plain-English notes about this quote.", "items": { "type": "string", "description": "One note." } }, "warnings": { "type": "array", "description": "Notices about the quote, such as a page count that had to be assumed.", "items": { "type": "string", "description": "One notice." } }, "rows_expected": { "type": "integer", "description": "Judged lists only: the most rows one call judges on this endpoint." }, "rows_cached": { "type": "integer", "description": "Judged lists only: rows already judged and free. 0 on a dry run, which sees no rows." }, "label_credits_min": { "type": "integer", "description": "Judged lists only: the least the paid labels add. 0 on a dry run, which sees no rows." }, "label_credits_max": { "type": "integer", "description": "Judged lists only: the most the paid labels can add. 0 when you asked for no paid label." }, "base_credits": { "type": "integer", "description": "Judged lists only: the call's price without the label and relevance holds." } } }, "held_back": { "type": "object", "description": "Present when you sent `fit=goal` with a `goal` and at least one block of the page was not needed for it. The held rows (or fields) stay in place as stubs of `{ id, held: true }`; this block lists them.", "properties": { "ids": { "type": "array", "description": "Ids of the rows or fields that were held back.", "items": { "type": "string", "description": "A row id." } }, "recall": { "type": "string", "description": "A recall id for the full page, which re-reads it from cache at no extra charge.", "example": "fit_3f9a1c0b7d2e4a58" } } }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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, "credits_remaining": 9999, "request_id": "req-8Kq2ZmR4vT9xLb3P", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWVNJc0ltTWlPaUp6WXpFdVpYbEtha2xxYjJsWGFrcFhUVVpuZVU1WGVHdE5iRm8yV2tWWk5XSlhSbGxUYm5CclVYcENNRlZVU210aWJFNVlXa1ZLVmxac2NFaFVha3BoVlRGUmQxTnJjRk5oTURWUFYycEthMU5HUmxaU2JGSlNZa1ZhZDFkclZuTlJNVzkzVTJ0YVlVMVdXa3RaVmxaUFVXeGtWbEpyVGxSV1ZuQkZWWHBLYTJKc1NYZFNhMHBXVFVWd1UxbFdWbTlUYkVaMFdrVktVMVl5VWxkVk1XTXhZMFpHVjJKRlNsSmhNbmhJVlZSQ2MyTnNiM2RhUlVwU1ZqSjRSbGRxU1RWVWJFVjNaRWQ0WVUxVVp6RldiRlpyVW14TmVXRjZSazlTV0VKRFZXdGFWMUZzUm5OaVJVcFdWVlF3T1VscGQybGplVWsyVjNsS1Zsb3pjRzVhVkUwd1RVZFNRMW93U1ROT1YyaFlVVzB3TVU1RlJtaFJWVXBDV25sSmMwbHNWbTVsYlhCRVlrVjRNVmd3ZEVsak1GSlhWakpvYkZJelp6QlJWMFpDVVd0R2JrbHNNVGtpZlEiLCJlIjoieW91dHViZS92aWRlby9jb21tZW50cyIsInAiOiJjb250aW51YXRpb25Ub2tlbiJ9", "has_more": true, "page_size": 2 } } } } }, "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" } } } } } } }, "/facebook/marketplace/location/search": { "get": { "summary": "Search Facebook Marketplace locations", "description": "Searches Facebook Marketplace locations and cities, returning lat/lng coordinates you can feed into `/v1/facebook/marketplace/search`.", "tags": [ "facebook" ], "operationId": "get_facebook_marketplace_location_search", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Location search query (city or area name).", "schema": { "type": "string" }, "example": "Los Angeles" }, { "name": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 120 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 120 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/marketplace/location/search" }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/marketplace/location/search", "data": { "items": [ { "name": "Los Angeles", "subtitle": "9830 · Los Ángeles, Distrito Federal, Mexico · 4,342 people checked in here", "multi_line_address": [], "page_id": "811991068870681", "latitude": 19.34838188, "longitude": -99.074028995, "city": "Iztapalapa", "postal_code": "09830" }, { "name": "Los Angeles", "subtitle": "Los Ángeles, Coahuila de Zaragoza, Mexico · 368 people checked in here", "multi_line_address": [], "page_id": "343463319102557", "latitude": 25.546767716667, "longitude": -103.45965151667, "city": "Torreón", "postal_code": "27160" } ], "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": null, "has_more": false, "page_size": 10 }, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/marketplace/search": { "get": { "summary": "Search Facebook Marketplace listings", "description": "Searches Facebook Marketplace listings by keyword + lat/lng with price, condition, delivery, and date-listed filters. Forward the returned cursor for additional pages. With `sort_by=creation_time_descend`, FB may return slightly different ordering across identical requests: for alerting workflows, scrape multiple pages and dedupe by listing id rather than assuming stable order.", "tags": [ "facebook" ], "operationId": "get_facebook_marketplace_search", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search keyword (e.g., `bike`, `couch`).", "schema": { "type": "string" }, "example": "bike" }, { "name": "lat", "in": "query", "required": true, "description": "Latitude of the search location.", "schema": { "type": "string" }, "example": "40.7128" }, { "name": "lng", "in": "query", "required": true, "description": "Longitude of the search location.", "schema": { "type": "string" }, "example": "-74.0060" }, { "name": "radius_km", "in": "query", "required": false, "description": "Search radius in kilometers.", "schema": { "type": "integer" } }, { "name": "min_price", "in": "query", "required": false, "description": "Minimum listing price.", "schema": { "type": "integer" } }, { "name": "max_price", "in": "query", "required": false, "description": "Maximum listing price.", "schema": { "type": "integer" } }, { "name": "count", "in": "query", "required": false, "description": "Number of listings to return per page. Native upstream page-size param. Send the universal `limit` instead: the API maps it to this name for you.", "deprecated": true, "schema": { "type": "integer" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort order for results.", "schema": { "type": "string", "enum": [ "suggested", "distance_ascend", "creation_time_descend", "price_ascend", "price_descend" ] } }, { "name": "delivery_method", "in": "query", "required": false, "description": "Delivery filter: local pickup only, shipping only, or all.", "schema": { "type": "string", "enum": [ "all", "local_pickup", "shipping" ] } }, { "name": "condition", "in": "query", "required": false, "description": "Filter listings by item condition.", "schema": { "type": "string", "enum": [ "new", "used_like_new", "used_good", "used_fair" ] } }, { "name": "date_listed", "in": "query", "required": false, "description": "Filter by listing recency (relative window or numeric day count).", "schema": { "type": "string", "enum": [ "all", "1", "7", "30", "last_24_hours", "last_7_days", "last_30_days" ] } }, { "name": "availability", "in": "query", "required": false, "description": "Filter by listing status: `available`, `sold`, or `all`.", "schema": { "type": "string", "enum": [ "available", "sold", "all" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor returned by the previous response: forward as-is.", "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": "limit", "in": "query", "required": false, "description": "Universal page size. The API maps it to this endpoint's native `count`.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 120 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 120 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/marketplace/search" }, "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." }, "walk": { "type": "object", "description": "Present when the request sent a row-walk param (`max_pages` above 1, `max_items`, `max_credits`, a row filter, `sort_rows` or `seen`). What the walk did across the pages it fetched. Each page is billed as one call, and its charge is recorded under its own request id.", "properties": { "pages": { "type": "integer", "description": "Pages fetched.", "example": 3 }, "stopped": { "type": "string", "enum": [ "end", "max_pages", "max_items", "max_credits", "time_budget", "page_error" ], "description": "Why the walk stopped. `end`: the list ran out. `max_pages`, `max_items` or `max_credits`: the limit you set was reached. `time_budget`: the request's time budget ran low. `page_error`: a later page failed. Unless it is `end`, `pagination.next_cursor` continues from where the walk stopped.", "example": "max_pages" }, "rows_fetched": { "type": "integer", "description": "Rows read across every page, before any filter.", "example": 60 }, "rows_returned": { "type": "integer", "description": "Rows in `data.items`.", "example": 41 }, "discarded": { "type": "object", "description": "Present when you sent a row filter. Rows the filters removed, counted once each under the first filter they failed. A row a filter cannot verify (no view count, no date, no country) is discarded.", "properties": { "views_below_min": { "type": "integer", "description": "Rows with fewer views than `min_views`." }, "views_unknown": { "type": "integer", "description": "Rows with no view count, when `min_views` was sent." }, "older_than_max_age": { "type": "integer", "description": "Rows published before the `max_age_days` window." }, "date_unknown": { "type": "integer", "description": "Rows with no publish date, when `max_age_days` was sent." }, "country_not_included": { "type": "integer", "description": "Rows registered to a country that is not in `country`." }, "country_unknown": { "type": "integer", "description": "Rows with no country, when `country` was sent." }, "country_excluded": { "type": "integer", "description": "Rows registered to a country listed in `exclude_country`." } } }, "repeats": { "type": "integer", "description": "Present when you sent `seen`: rows removed because your account already received them under that id." }, "duplicates": { "type": "integer", "description": "Present when above zero: rows a later page repeated from an earlier page of the same walk, kept once." }, "credits": { "type": "object", "description": "What the pages cost.", "properties": { "pages": { "type": "integer", "description": "Credits charged for the pages walked, before refunds." }, "refunded": { "type": "integer", "description": "Credits refunded across the pages." } } }, "request_ids": { "type": "array", "description": "The request id of each page walked. Each is its own entry in `GET /v1/credits/transactions`.", "items": { "type": "string", "description": "A row id." } } } }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/marketplace/search", "data": { "items": [ { "id": "1122353233771500", "url": "https://www.facebook.com/marketplace/item/1122353233771500/", "title": "Outroad bike", "creation_time": "2026-09-20T16:43:18.000Z", "listing_date_text": "Listed 1 week ago", "mileage": null, "custom_subtitles": [], "price": { "formatted_amount": "$110", "amount_with_offset_in_currency": 11000, "amount": 110 }, "strikethrough_price": null, "location": { "city": "New York", "state": "NY", "display_name": "user_4cf4fc", "city_page_id": "108424279189115" }, "primary_photo": { "id": "2077250419830237", "url": "https://scontent-lga3-2.xx.fbcdn.net/v/t39.84726-6/819103741_2077250429830236_5380313198372039283_n.jpg?stp=c43.0.260.260a_dst-jpg_p261x260_tt6&_nc_cat=107&ccb=1-7&_nc_sid=92e707&_nc_ohc=jmqkWp0vZEcQ7kNvwEIYsSk&_nc_oc=Adq-NWqd1uwQd5WDeU2Ix12nf0qZhBAzaDlNj1pVdYQr8XomEZ5npAS0HmUcNPjUf0s&_nc_zt=14&_nc_ht=scontent-lga3-2.xx&_nc_gid=M0mJLnxcmk9-WntMu2iXQw&_nc_ss=78289&oh=00_AQPGqQoX5dRmVxPxLF0h9_zi7067CdEwROyr5Mn00VuWPA&oe=6AC52372" }, "category_id": "1658310421102081", "is_hidden": false, "is_live": true, "is_pending": false, "is_sold": false, "is_viewer_seller": false, "delivery_types": [ "IN_PERSON" ], "story_type": "POST", "story_key": "28697064483290941" }, { "id": "1455642709743277", "url": "https://www.facebook.com/marketplace/item/1455642709743277/", "title": "Bike", "creation_time": "2026-09-07T20:01:04.000Z", "listing_date_text": "Listed 3 weeks ago", "mileage": null, "custom_subtitles": [], "price": { "formatted_amount": "$40", "amount_with_offset_in_currency": 4000, "amount": 40 }, "strikethrough_price": null, "location": { "city": "Plainfield", "state": "NJ", "display_name": "user_4d7872", "city_page_id": "107725169250666" }, "primary_photo": { "id": "1784176079285974", "url": "https://scontent-lga3-2.xx.fbcdn.net/v/t39.84726-6/799682621_1784176082619307_8403579089542611394_n.jpg?stp=c42.0.260.260a_dst-jpg_p261x260_tt6&_nc_cat=101&ccb=1-7&_nc_sid=92e707&_nc_ohc=HnyCmoXW9lYQ7kNvwG4d2Pw&_nc_oc=AdqC2hAB2gdsKYwigM1HUl8Bg2UhRpBo07ov6SRMdcmyAq0MhpDG8oTT5yqXWRCszYA&_nc_zt=14&_nc_ht=scontent-lga3-2.xx&_nc_gid=M0mJLnxcmk9-WntMu2iXQw&_nc_ss=78289&oh=00_AQPCelOTDmhVAgOh4MKUO9GUdGEwSNVnfg118iEIsE9G9A&oe=6AC54A9C" }, "category_id": "1658310421102081", "is_hidden": false, "is_live": true, "is_pending": false, "is_sold": false, "is_viewer_seller": false, "delivery_types": [ "IN_PERSON" ], "story_type": "POST", "story_key": "28191870387089528" } ], "next_cursor": "eyJwZyI6MCwiYjJjIjp7ImJyIjoiIiwiaXQiOjAsImhtc3IiOmZhbHNlLCJ0YmkiOjB9LCJjMmMiOnsiYnIiOiJBYm8xZVlnUE1maldUaVNGTkVERDVFUEgydFlyZUVpQ2JmU2tWZ2hJRjlqYXREQThpSDBJSWE0dVVmQTZHQzdsR1JZd3FkZjViQWN6WWdDbmkxcV9SclNsTXdTMUd3MFlDMG1BUEhpVEFVWGRINTA4Q2dmSFBmZlgxUXh5X0ZhOWQ5eVdHVGUzS2dwaEdVTS1wT1lHUG9ZQW5wNGY2WTFiWlpPWm9zeUdyTzFBYXZYZGVMdGM3dlE1SUpxenJuQ2d4cTVRNlFJOE1SRGluRkVYdWt5eGtabzJzNnlCRjAxQUw3RzdkZHJyMEphV0hHcjY5em5Hc19kNC1VVEI4RlV6LUx3REthUGFwdXc2RFRKcDU2QXlEZGhYMHh6MFk3dzFUbWJPTVI1ZmVaZ0ZsYkpzMVdfbmZMaDdBRUxPN1g1VkcxM3R4dDl0RFRSVnpxSnJpRVZybVl5TzZfWGdYV3NTVGtOTUlKWkdLSV9TWnlodllmazZCdjBiTEVVUVFwM2Nwd0QwSy1hN0l5TFdvX2M4MkNRbGNMX2c2ZU1GMjhIMWZzUHRYSDhHSkk3bkhITi1jSVItWFE0V0RrMm9Ib090a1NKQmQta015VGhtZjhHc0Y1a1VTSThZcmNyNGw2N2JkcWdCbEJMN2dWZW9zUkw1U0NHSENxT3Rza1M5eWUtMnc4TVZ6RXBEMkhUNmlGSXFKWGs1QjFNaWNGckZfSzlRX045MnhsdUcxaXNLYUNsZ0R0N2xuMFZ3Qk9vQ1JtNnUxdTgiLCJpdCI6MCwicnBiciI6IiIsInJwaHIiOmZhbHNlLCJybWhyIjpmYWxzZSwic3NpIjpmYWxzZSwic3NjbyI6MCwic3NwaSI6WyIyODY5NzA2NDQ4MzI5MDk0MSIsIjI4MTkxODcwMzg3MDg5NTI4IiwiMjc2Nzg5NzA5NTE2OTk0NjkiLCIyNzcxNTI0MDU4MTQ3MDgxMiIsIjM3ODU3Nzg0MTQ3MjAxNzA2IiwiMjg3NDU2NTIyNjg0NTM0MTciLCIyNzY1MTAyMTgyNDU3ODc4NSIsIjI4NDMxMjg2MTgzMTM1NDI3IiwiMjg3NDM3NDU2MTUyMTQyNjQiLCIzODE0MzI0OTIyODYyMjgxOCIsIjI4MTA0MzIyNTkyNTU4NDI3IiwiMzc5NjkzNDY3NTYwNDMxMTYiXX0sImlyciI6ZmFsc2UsInNlcnBfY3RhIjpmYWxzZSwicnVpIjpbXSwibXBpZCI6W10sInVicCI6bnVsbCwibmNybmQiOjAsImlyc3IiOmZhbHNlLCJibXByIjpbXSwiYm1wZWlkIjpbXSwibm1ibXAiOmZhbHNlLCJza3JyIjpmYWxzZSwiaW9vdXIiOmZhbHNlLCJpc2UiOmZhbHNlLCJzbXNfY3Vyc29yIjp7InBhZ2VfaW5kZXgiOjAsImJsZW5kZWRfYWRfaW5kZXgiOjAsIm9yZ2FuaWNzX3NpbmNlX2xhc3RfYWQiOjAsInBhZ2Vfb3JnYW5pY19jb3VudCI6MCwiYmxlbmRlZF9vcmdhbmljX2luZGV4IjowLCJyZXR1cm5lZF9hZF9pbmRleCI6MCwidG90YWxfaW5kZXgiOjB9fQ", "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiZXlKd1p5STZNQ3dpWWpKaklqcDdJbUp5SWpvaUlpd2lhWFFpT2pBc0ltaHRjM0lpT21aaGJITmxMQ0owWW1raU9qQjlMQ0pqTW1NaU9uc2lZbklpT2lKQlltOHhaVmxuVUUxbWFsZFVhVk5HVGtWRVJEVkZVRWd5ZEZseVpVVnBRMkptVTJ0V1oyaEpSamxxWVhSRVFUaHBTREJKU1dFMGRWVm1RVFpIUXpkc1IxSlpkM0ZrWmpWaVFXTjZXV2REYm1reGNWOVNjbE5zVFhkVE1VZDNNRmxETUcxQlVFaHBWRUZWV0dSSU5UQTRRMmRtU0ZCbVpsZ3hVWGg1WDBaaE9XUTVlVmRIVkdVelMyZHdhRWRWVFMxd1QxbEhVRzlaUVc1d05HWTJXVEZpV2xwUFdtOXplVWR5VHpGQllYWllaR1ZNZEdNM2RsRTFTVXB4ZW5KdVEyZDRjVFZSTmxGSk9FMVNSR2x1UmtWWWRXdDVlR3RhYnpKek5ubENSakF4UVV3M1J6ZGtaSEp5TUVwaFYwaEhjalk1ZW01SGMxOWtOQzFWVkVJNFJsVjZMVXgzUkV0aFVHRndkWGMyUkZSS2NEVTJRWGxFWkdoWU1IaDZNRmszZHpGVWJXSlBUVkkxWm1WYVowWnNZa3B6TVZkZmJtWk1hRGRCUlV4UE4xZzFWa2N4TTNSNGREbDBSRlJTVm5weFNuSnBSVlp5YlZsNVR6WmZXR2RZVjNOVFZHdE9UVWxLV2tkTFNWOVRXbmxvZGxsbWF6WkNkakJpVEVWVlVWRndNMk53ZDBRd1N5MWhOMGw1VEZkdlgyTTRNa05SYkdOTVgyYzJaVTFHTWpoSU1XWnpVSFJZU0RoSFNrazNia2hJVGkxalNWSXRXRkUwVjBSck1tOUliMDkwYTFOS1FtUXRhMDE1VkdodFpqaEhjMFkxYTFWVFNUaFpjbU55Tkd3Mk4ySmtjV2RDYkVKTU4yZFdaVzl6VWt3MVUwTkhTRU54VDNSemExTTVlV1V0TW5jNFRWWjZSWEJFTWtoVU5tbEdTWEZLV0dzMVFqRk5hV05HY2taZlN6bFJYMDQ1TW5oc2RVY3hhWE5MWVVOc1owUjBOMnh1TUZaM1FrOXZRMUp0Tm5VeGRUZ2lMQ0pwZENJNk1Dd2ljbkJpY2lJNklpSXNJbkp3YUhJaU9tWmhiSE5sTENKeWJXaHlJanBtWVd4elpTd2ljM05wSWpwbVlXeHpaU3dpYzNOamJ5STZNQ3dpYzNOd2FTSTZXeUl5T0RZNU56QTJORFE0TXpJNU1EazBNU0lzSWpJNE1Ua3hPRGN3TXpnM01EZzVOVEk0SWl3aU1qYzJOemc1TnpBNU5URTJPVGswTmpraUxDSXlOemN4TlRJME1EVTRNVFEzTURneE1pSXNJak0zT0RVM056ZzBNVFEzTWpBeE56QTJJaXdpTWpnM05EVTJOVEl5TmpnME5UTTBNVGNpTENJeU56WTFNVEF5TVRneU5EVTNPRGM0TlNJc0lqSTRORE14TWpnMk1UZ3pNVE0xTkRJM0lpd2lNamczTkRNM05EVTJNVFV5TVRReU5qUWlMQ0l6T0RFME16STBPVEl5T0RZeU1qZ3hPQ0lzSWpJNE1UQTBNekl5TlRreU5UVTROREkzSWl3aU16YzVOamt6TkRZM05UWXdORE14TVRZaVhYMHNJbWx5Y2lJNlptRnNjMlVzSW5ObGNuQmZZM1JoSWpwbVlXeHpaU3dpY25WcElqcGJYU3dpYlhCcFpDSTZXMTBzSW5WaWNDSTZiblZzYkN3aWJtTnlibVFpT2pBc0ltbHljM0lpT21aaGJITmxMQ0ppYlhCeUlqcGJYU3dpWW0xd1pXbGtJanBiWFN3aWJtMWliWEFpT21aaGJITmxMQ0p6YTNKeUlqcG1ZV3h6WlN3aWFXOXZkWElpT21aaGJITmxMQ0pwYzJVaU9tWmhiSE5sTENKemJYTmZZM1Z5YzI5eUlqcDdJbkJoWjJWZmFXNWtaWGdpT2pBc0ltSnNaVzVrWldSZllXUmZhVzVrWlhnaU9qQXNJbTl5WjJGdWFXTnpYM05wYm1ObFgyeGhjM1JmWVdRaU9qQXNJbkJoWjJWZmIzSm5ZVzVwWTE5amIzVnVkQ0k2TUN3aVlteGxibVJsWkY5dmNtZGhibWxqWDJsdVpHVjRJam93TENKeVpYUjFjbTVsWkY5aFpGOXBibVJsZUNJNk1Dd2lkRzkwWVd4ZmFXNWtaWGdpT2pCOWZRIiwiZSI6ImZhY2Vib29rL21hcmtldHBsYWNlL3NlYXJjaCIsInAiOiJjdXJzb3IifQ", "has_more": true, "page_size": 12 }, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/marketplace/item": { "get": { "summary": "Get a Facebook Marketplace item", "description": "Fetches a single Facebook Marketplace listing. The canonical Post leaves carry the title (`content.text`), the photos (`content.media_urls`) and the listing permalink; everything that makes it a LISTING rides `post.ext.commerce`: `price` (a number) with `currency` and `price_formatted`, `strikethrough_price_formatted` when the seller cut the price, the full `description`, `location_text` with `latitude` and `longitude`, `attributes[]` (where the condition lives, e.g. `{attribute_name: \"Condition\", label: \"Used - Good\"}`), `category_id`, `mileage` on vehicles, `delivery_types`, and the availability flags `is_sold`, `is_live`, `is_pending`, `is_hidden`, `is_shipping_offered`, `is_buy_now_enabled` and `messaging_enabled`. The engagement leaves stay null: Facebook publishes no public like or comment count on a listing. Pass either the numeric `id` or a full Marketplace `url`.", "tags": [ "facebook" ], "operationId": "get_facebook_marketplace_item", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-socialcrawl-oneOf": [ [ "id", "url" ] ], "parameters": [ { "name": "id", "in": "query", "required": false, "description": "Facebook Marketplace item ID (numeric). (one of: id, url; at least one required)", "schema": { "type": "string" } }, { "name": "url", "in": "query", "required": false, "description": "Full URL of the Marketplace item. (one of: id, url; at least one required)", "schema": { "type": "string" }, "example": "https://www.facebook.com/marketplace/item/1656586118821988/" }, { "name": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 600 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 3600 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/marketplace/item" }, "data": { "type": "object", "description": "Platform-specific response data", "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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "number", "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": [ "number", "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": [ "number", "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", "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "number", "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; discover reads a country from it into `geo.country` (`source: author_location`). 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": [ "number", "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" }, "link_domain": { "type": [ "string", "null" ], "description": "String at post.ext.link_domain" }, "upvote_ratio": { "type": [ "number", "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" ], "enum": [ "video", "short", "live", "channel", "playlist", 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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "enum": [ "image", "video", "carousel", 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": [ "number", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": { "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": { "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": [ "object", "null" ], "description": "Object 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": { "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/profile/posts`, `/v1/instagram/profile/reels`, `/v1/instagram/search/reels`, `/v1/tiktok/profile/videos` 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": [ "object", "null" ], "description": "Object 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", "enum": [ "image", "video" ], "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "number", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "number", "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": [ "number", "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": [ "object", "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": [ "object", "null" ], "description": "Object at post.ext.retweeted_post" }, "quote_count": { "type": [ "number", "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": { "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": [ "object", "null" ], "description": "Object 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": "object", "description": "Object 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": [ "number", "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": [ "object", "null" ], "description": "Object at post.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: post.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.description" } } } }, "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" ], "enum": [ "minute", "hour", "day", "week", "month", "year", 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": [ "number", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "number", "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": [ "object", "null" ], "description": "Object 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": [ "number", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "object", "null" ], "description": "Object at post.ext.dsp_ids", "additionalProperties": { "type": "string", "description": "String 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": "object", "description": "Object at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "object", "description": "Object at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "object", "description": "Object 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": [ "object", "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": [ "object", "null" ], "description": "Object 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": [ "number", "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": "number", "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": [ "object", "null" ], "description": "Object at post.ext.event" }, "trend": { "type": [ "object", "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" }, "numeric_id": { "type": [ "number", "null" ], "description": "Numeric at post.ext.numeric_id" }, "outbound_url": { "type": [ "string", "null" ], "description": "String at post.ext.outbound_url" }, "group": { "type": [ "object", "null" ], "description": "Object at post.ext.group" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "number", "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": [ "number", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "number", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "number", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "enum": [ "target", "other_named_thing", "generic_word", "not_present" ], "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "number", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "number", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "string", "boolean", "null" ], "description": "Union: number | string | boolean" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } } } }, "_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": [ "post" ] }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/marketplace/item", "data": { "post": { "id": "1656586118821988", "url": "https://www.facebook.com/marketplace/item/1656586118821988/", "content": { "text": "‘95 Specialized Hardrock GSX - Super Clean Vintage Gravel Restomod - INCLUDES FREE TUNE UP", "media_urls": [ "https://scontent-sjc6-1.xx.fbcdn.net/v/t39.84726-6/701290950_2810586459318376_3780262866029042186_n.jpg?stp=dst-jpg_s960x960_tt6&_nc_cat=111&ccb=1-7&_nc_sid=92e707&_nc_ohc=gfilbGgPZTkQ7kNvwFciV29&_nc_oc=Adpm5sbFtev6pNVfI_o8-gifqqi56rJqvSFqvly1kQQGC1AMiDiP3JG1pzRLAsREB-A&_nc_zt=14&_nc_ht=scontent-sjc6-1.xx&_nc_gid=FG0_9MKD6EeBRFzhlsmjiQ&_nc_ss=78289&oh=00_AQMJIrn2wa_jUIjnX3nUVU1NMDntWqjN7gxwvOpBRbBsSw&oe=6AC56556", "https://scontent-sjc3-1.xx.fbcdn.net/v/t45.5328-4/697073866_970558555581619_2491053447787511025_n.jpg?stp=dst-jpg_s960x960_tt6&_nc_cat=103&ccb=1-7&_nc_sid=247b10&_nc_ohc=qOsEKxHp5NIQ7kNvwGLDB3_&_nc_oc=Adp3Y3lPvqAXXCD6HlnB6m0mQ8nrpAwxPAkhQUHZBbzll_n3WlXLUunTVJz7kM2bw9I&_nc_zt=23&_nc_ht=scontent-sjc3-1.xx&_nc_gid=FG0_9MKD6EeBRFzhlsmjiQ&_nc_ss=78289&oh=00_AQN1m9HKt4zs-vqgjGVwSaCrH0UvWitj8X2n3Ko8OH1RDg&oe=6AC583AE" ], "thumbnail_url": null, "duration_seconds": null }, "author": { "username": null, "display_name": null, "avatar_url": null, "verified": null }, "engagement": { "views": null, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-05-15T16:57:39.000Z", "ext": { "commerce": { "price": 220, "currency": "USD", "price_formatted": "$220", "strikethrough_price_formatted": "$380", "description": "Was going to hang on to this one bc I absolutely love how it looks, but the 20” frame is just bit too large for me. Riders over 6’ would be comfy on this one. Currently in a 3x7, drop bar mtb set up with an XT derailleur at the rear. Looks great in person. Come ride it!\n\nCASH ONLY, PLEASE. NEAR 183/BRAKER. \n\n$260 OBO. \n\nKey points:\n\n- Maxxis DTH tires (26”)\n- Shimano Deore XT rear derailleur \n- Shimano front derailleur\n- vintage Specialized steel frame (20”)\n- vintage Sakae triple crankset (170mm)\n- vintage Sakae SR Custom handlebar\n- vintage Suntour stem shifter\n- vintage Shimano brakes\n- Specialized Avatar 143 saddle\n- new chain\n- fresh cables\n- fresh housing\n- fresh grease and lube\n- fresh lube in cable housings\n- fresh handlebar tape\n- drive train cleaned and lubed\n- derailluers adjusted and fine tuned\n- brakes adjusted and fine tuned\n- deep cleaning/detail\n- frame polished\n- frame waxed\n- INCLUDES ONE FREE TUNE U", "location_text": "Austin, TX", "latitude": 30.401916503906, "longitude": -97.761840820312, "category_id": "1658310421102081", "mileage": null, "attributes": [ { "attribute_name": "Condition", "value": "used_good", "label": "Used - Good" }, { "attribute_name": "Bicycle Type", "value": "Mountain Bike", "label": "Mountain Bike" } ], "delivery_types": [ "IN_PERSON" ], "availability_text": null, "listing_date_text": "Listed 4 months ago", "is_sold": true, "is_live": true, "is_pending": false, "is_hidden": false, "is_shipping_offered": false, "is_buy_now_enabled": false, "messaging_enabled": true, "seller_id": null, "seller_name": null } } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": null } }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/events/search": { "get": { "summary": "Search Facebook events by keyword", "description": "Searches the public Facebook Events directory for events matching a keyword. Forward the returned cursor for additional pages.", "tags": [ "facebook" ], "operationId": "get_facebook_events_search", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Event name or keyword to search for.", "schema": { "type": "string" }, "example": "dogs" }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor returned by the previous response for pagination.", "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": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 120 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 120 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/events/search" }, "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." }, "walk": { "type": "object", "description": "Present when the request sent a row-walk param (`max_pages` above 1, `max_items`, `max_credits`, a row filter, `sort_rows` or `seen`). What the walk did across the pages it fetched. Each page is billed as one call, and its charge is recorded under its own request id.", "properties": { "pages": { "type": "integer", "description": "Pages fetched.", "example": 3 }, "stopped": { "type": "string", "enum": [ "end", "max_pages", "max_items", "max_credits", "time_budget", "page_error" ], "description": "Why the walk stopped. `end`: the list ran out. `max_pages`, `max_items` or `max_credits`: the limit you set was reached. `time_budget`: the request's time budget ran low. `page_error`: a later page failed. Unless it is `end`, `pagination.next_cursor` continues from where the walk stopped.", "example": "max_pages" }, "rows_fetched": { "type": "integer", "description": "Rows read across every page, before any filter.", "example": 60 }, "rows_returned": { "type": "integer", "description": "Rows in `data.items`.", "example": 41 }, "discarded": { "type": "object", "description": "Present when you sent a row filter. Rows the filters removed, counted once each under the first filter they failed. A row a filter cannot verify (no view count, no date, no country) is discarded.", "properties": { "views_below_min": { "type": "integer", "description": "Rows with fewer views than `min_views`." }, "views_unknown": { "type": "integer", "description": "Rows with no view count, when `min_views` was sent." }, "older_than_max_age": { "type": "integer", "description": "Rows published before the `max_age_days` window." }, "date_unknown": { "type": "integer", "description": "Rows with no publish date, when `max_age_days` was sent." }, "country_not_included": { "type": "integer", "description": "Rows registered to a country that is not in `country`." }, "country_unknown": { "type": "integer", "description": "Rows with no country, when `country` was sent." }, "country_excluded": { "type": "integer", "description": "Rows registered to a country listed in `exclude_country`." } } }, "repeats": { "type": "integer", "description": "Present when you sent `seen`: rows removed because your account already received them under that id." }, "duplicates": { "type": "integer", "description": "Present when above zero: rows a later page repeated from an earlier page of the same walk, kept once." }, "credits": { "type": "object", "description": "What the pages cost.", "properties": { "pages": { "type": "integer", "description": "Credits charged for the pages walked, before refunds." }, "refunded": { "type": "integer", "description": "Credits refunded across the pages." } } }, "request_ids": { "type": "array", "description": "The request id of each page walked. Each is its own entry in `GET /v1/credits/transactions`.", "items": { "type": "string", "description": "A row id." } } } }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/events/search", "data": { "items": [ { "id": "1017864737699512", "name": "Save the Dogs Protest at Amgen Pharmaceuticals", "type": "Event", "url": "https://www.facebook.com/events/1017864737699512/", "day_time_sentence": "Monday, August 3, 2026 at 12:30 PM PDT", "event_place": { "__typename": "FreeformPlace", "name": "Park & Ride-Rancho Conejo Blvd", "contextual_name": "Park & Ride-Rancho Conejo Blvd", "__isNode": "FreeformPlace", "id": "1482809863890045" }, "ticketing_context_row": { "price_range_text": null }, "is_online": false, "is_past": true, "event_url": "https://www.facebook.com/events/1017864737699512/", "event_kind": "PUBLIC_TYPE", "start_timestamp": 1785785400, "cover_photo": { "eventImage": { "uri": "https://scontent-phl2-1.xx.fbcdn.net/v/t39.30808-6/759373646_1482807013890330_711987034836688581_n.jpg?_nc_cat=111&ccb=1-7&_nc_sid=75d36f&_nc_ohc=pI4uZSy6F08Q7kNvwGcTzMs&_nc_oc=Ado0y_drr4aOmwENoJzcPQM2vvcFbHmSqWBUzukAe9KzkWvJC5FjCVOP0HkKYAXyDE8&_nc_zt=23&_nc_ht=scontent-phl2-1.xx&_nc_gid=_rNL2_OBnOanNnTG9rqqzA&_nc_ss=78289&oh=00_AQNyOAPWrZWL_Si5zVkFqN5RR3QWIvloePCodTxH4DirbA&oe=6AC5189B" } }, "social_context": { "text": "4 interested · 4 going", "interested_count": 4, "going_count": 4, "went_count": null } }, { "id": "1113752917820733", "name": "Beginners/bronze dog training for pups or older sociable dogs.", "type": "Event", "url": "https://www.facebook.com/events/1113752917820733/", "day_time_sentence": "Wednesday, October 28, 2026 at 5:15 PM GMT", "event_place": { "__typename": "FreeformPlace", "name": "Tytherington", "contextual_name": "Tytherington", "__isNode": "FreeformPlace", "id": "1814588026869621" }, "ticketing_context_row": { "price_range_text": null }, "is_online": false, "is_past": false, "event_url": "https://www.facebook.com/events/1113752917820733/", "event_kind": "PUBLIC_TYPE", "start_timestamp": 1793207700, "cover_photo": { "eventImage": { "uri": "https://scontent-sjc6-1.xx.fbcdn.net/v/t39.30808-6/825286541_1814521090209648_6351502321458409921_n.jpg?_nc_cat=104&ccb=1-7&_nc_sid=75d36f&_nc_ohc=q55dwlm6xXEQ7kNvwFSRufB&_nc_oc=AdpuF_3d5OiKGy6cxfmu23bi7FPGxP_nd13kbQukh0nIQhGwHketEnKMRITcIGwUIOI&_nc_zt=23&_nc_ht=scontent-sjc6-1.xx&_nc_gid=Ufo4oFA9Eujboah2YjNDRA&_nc_ss=78289&oh=00_AQPk7SVhVem-PwadosTPyMCPJ3TZwM97AzYw6wSB_9q6qQ&oe=6AC5229E" } }, "social_context": { "text": "5 interested · 1 going", "interested_count": 5, "going_count": 1, "went_count": null } } ], "next_cursor": "2", "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiMiIsImUiOiJmYWNlYm9vay9ldmVudHMvc2VhcmNoIiwicCI6ImN1cnNvciJ9", "has_more": true, "page_size": 5 }, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/events": { "get": { "summary": "List Facebook events for a city", "description": "Returns the events listed under a Facebook city or region Events explore page. **The `url` must be an Events explore URL ending in the numeric location id** (see the example); a plain page URL is rejected with a 400 at 0 credits, and a single page's OWN events are `/v1/facebook/profile/events`. Each row carries the title, the permalink, the cover image, the start time, the RSVP counts, and on `post.ext.event` the rendered time line (`time_text`), `location_name` (the venue), `start_timestamp`, `is_online`, `is_past`, `interested_count` and `going_count`. The same two reading notes apply as on that endpoint: `published_at` is the event's START time and is routinely in the future, and `engagement.views` and `engagement.likes` carry the interested and going RSVP counts because an event has no views or likes. The explore listing carries no description, address, city, host or category, so those are null on a plain call. Send `include=details` and every event is joined, in the same call, to the per-event details lookup: the description, the street address and city, the coordinates, the hosts (`hosts[]`, and the one-line host credit on `post.author.display_name` and `post.ext.event.host_context_text`), the category, the privacy, the cancelled flag and the attendance count land on each row, and a missing cover or RSVP count is filled where the details carry one. Values the row already carried are never replaced. Cost: 1 credit for the page plus 1 credit per event filled from a fresh lookup (at most 12 events a page, so 13 credits at most); rows already in cache are filled for free, rows that could not be filled are refunded, and a repeat of the same call within the cache window is 0 credits. Time: `include=details` adds 2 to 8 seconds on a fresh page (the lookups run in parallel and the call waits for the slowest, never more than 12 seconds) and nothing when the rows are already cached. The response carries a `hydration` block itemising rows, lookups, cache hits, credits and milliseconds. Filter by relative `time` (defaults to all time) and forward the returned cursor for additional pages.", "tags": [ "facebook" ], "operationId": "get_facebook_events", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 13, "x-credit-cost-formula": "1 credit for the page. include=details holds 1 credit per event (at most 12 a page) and keeps only the rows filled from a fresh lookup, so a page is at most 13 credits; rows served from cache are free, unfilled rows 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": "url", "in": "query", "required": true, "description": "Full URL of the city's Facebook Events page.", "schema": { "type": "string" }, "example": "https://www.facebook.com/events/explore/saint-petersburg-florida/111326725552547" }, { "name": "time", "in": "query", "required": false, "description": "Relative time window. Defaults to all time when omitted.", "schema": { "type": "string", "enum": [ "today", "this_week", "next_week" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor returned by the previous response for pagination.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Set to `details` (one token only) to fill, on every event in this one call, `post.ext.event.description`, `address`, `city`, `latitude`, `longitude`, `hosts`, `host_context_text`, `category`, `privacy`, `is_canceled` and `attendance_count`, and the host credit on `post.author.display_name`. Holds 1 credit per event (at most 12 a page) and keeps only the rows filled from a fresh lookup; rows already in cache and rows the lookup cannot fill are refunded, so a page is never more than 13 credits. The join takes 2 to 8 seconds on a fresh page, never more than 12, and nothing when the rows are already cached; read `data.hydration` for the rows, the credits held and kept, and the time. Without it the call is unchanged.", "schema": { "type": "string", "enum": [ "details" ] } }, { "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": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 600 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 3600 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/events" }, "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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "number", "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": [ "number", "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": [ "number", "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", "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "number", "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; discover reads a country from it into `geo.country` (`source: author_location`). 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": [ "number", "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" }, "link_domain": { "type": [ "string", "null" ], "description": "String at post.ext.link_domain" }, "upvote_ratio": { "type": [ "number", "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" ], "enum": [ "video", "short", "live", "channel", "playlist", 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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "enum": [ "image", "video", "carousel", 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": [ "number", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": { "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": { "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": [ "object", "null" ], "description": "Object 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": { "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/profile/posts`, `/v1/instagram/profile/reels`, `/v1/instagram/search/reels`, `/v1/tiktok/profile/videos` 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": [ "object", "null" ], "description": "Object 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", "enum": [ "image", "video" ], "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "number", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "number", "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": [ "number", "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": [ "object", "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": [ "object", "null" ], "description": "Object at post.ext.retweeted_post" }, "quote_count": { "type": [ "number", "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": { "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": [ "object", "null" ], "description": "Object 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": "object", "description": "Object 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": [ "number", "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": [ "object", "null" ], "description": "Object at post.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: post.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.description" } } } }, "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" ], "enum": [ "minute", "hour", "day", "week", "month", "year", 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": [ "number", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "number", "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": [ "object", "null" ], "description": "Object 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": [ "number", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "object", "null" ], "description": "Object at post.ext.dsp_ids", "additionalProperties": { "type": "string", "description": "String 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": "object", "description": "Object at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "object", "description": "Object at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "object", "description": "Object 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": [ "object", "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": [ "object", "null" ], "description": "Object 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": [ "number", "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": "number", "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": [ "object", "null" ], "description": "Object at post.ext.event" }, "trend": { "type": [ "object", "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" }, "numeric_id": { "type": [ "number", "null" ], "description": "Numeric at post.ext.numeric_id" }, "outbound_url": { "type": [ "string", "null" ], "description": "String at post.ext.outbound_url" }, "group": { "type": [ "object", "null" ], "description": "Object at post.ext.group" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "number", "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": [ "number", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "number", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "number", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "enum": [ "target", "other_named_thing", "generic_word", "not_present" ], "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "number", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "number", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "string", "boolean", "null" ], "description": "Union: number | string | boolean" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } } } } } } }, "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." }, "walk": { "type": "object", "description": "Present when the request sent a row-walk param (`max_pages` above 1, `max_items`, `max_credits`, a row filter, `sort_rows` or `seen`). What the walk did across the pages it fetched. Each page is billed as one call, and its charge is recorded under its own request id.", "properties": { "pages": { "type": "integer", "description": "Pages fetched.", "example": 3 }, "stopped": { "type": "string", "enum": [ "end", "max_pages", "max_items", "max_credits", "time_budget", "page_error" ], "description": "Why the walk stopped. `end`: the list ran out. `max_pages`, `max_items` or `max_credits`: the limit you set was reached. `time_budget`: the request's time budget ran low. `page_error`: a later page failed. Unless it is `end`, `pagination.next_cursor` continues from where the walk stopped.", "example": "max_pages" }, "rows_fetched": { "type": "integer", "description": "Rows read across every page, before any filter.", "example": 60 }, "rows_returned": { "type": "integer", "description": "Rows in `data.items`.", "example": 41 }, "discarded": { "type": "object", "description": "Present when you sent a row filter. Rows the filters removed, counted once each under the first filter they failed. A row a filter cannot verify (no view count, no date, no country) is discarded.", "properties": { "views_below_min": { "type": "integer", "description": "Rows with fewer views than `min_views`." }, "views_unknown": { "type": "integer", "description": "Rows with no view count, when `min_views` was sent." }, "older_than_max_age": { "type": "integer", "description": "Rows published before the `max_age_days` window." }, "date_unknown": { "type": "integer", "description": "Rows with no publish date, when `max_age_days` was sent." }, "country_not_included": { "type": "integer", "description": "Rows registered to a country that is not in `country`." }, "country_unknown": { "type": "integer", "description": "Rows with no country, when `country` was sent." }, "country_excluded": { "type": "integer", "description": "Rows registered to a country listed in `exclude_country`." } } }, "repeats": { "type": "integer", "description": "Present when you sent `seen`: rows removed because your account already received them under that id." }, "duplicates": { "type": "integer", "description": "Present when above zero: rows a later page repeated from an earlier page of the same walk, kept once." }, "credits": { "type": "object", "description": "What the pages cost.", "properties": { "pages": { "type": "integer", "description": "Credits charged for the pages walked, before refunds." }, "refunded": { "type": "integer", "description": "Credits refunded across the pages." } } }, "request_ids": { "type": "array", "description": "The request id of each page walked. Each is its own entry in `GET /v1/credits/transactions`.", "items": { "type": "string", "description": "A row id." } } } }, "hydration": { "type": "object", "description": "Present when the request asked for a row join with `include=`, or sent a param that implies one. What the join did and what it cost. On a multi-page walk it sums every page. A join that always runs for free is left out.", "properties": { "include": { "type": "string", "description": "The token that switched the join on.", "example": "profile" }, "implied_by": { "type": "string", "description": "Present when you did not send `include` and another param switched the join on. The join's credits (`extra_credits`) are then part of `credits_used`. Absent when you sent `include` yourself." }, "rows": { "type": "integer", "description": "Rows on the page after any row cap.", "example": 20 }, "looked_up": { "type": "integer", "description": "Rows that needed a lookup (at least one field the join fills was empty).", "example": 20 }, "filled": { "type": "integer", "description": "Rows where at least one field was filled by the join.", "example": 18 }, "cached": { "type": "integer", "description": "Of `filled`, rows filled from the sibling endpoint's cache at no charge.", "example": 0 }, "unfilled": { "type": "integer", "description": "Rows that needed a lookup and were not filled (the lookup failed, was skipped, or had nothing to copy). Their credits are refunded.", "example": 2 }, "credits_held": { "type": "integer", "description": "Credits held up front for the join, on top of the page's own price.", "example": 20 }, "extra_credits": { "type": "integer", "description": "Of `credits_held`, the credits kept: one lookup's price for each distinct key filled from a fresh lookup. The rest was refunded.", "example": 18 }, "ms": { "type": "integer", "description": "Time the join added, in milliseconds.", "example": 2400 }, "cached_page": { "type": "boolean", "description": "True when the whole page was served from cache, so the join cost nothing on this call.", "example": true }, "batches": { "type": "integer", "description": "Joins that look rows up in batches only: how many batch calls were made. Absent on a join that looks rows up one by one." }, "from_earlier_pages": { "type": "integer", "description": "`max_pages`, `max_items` and `max_credits` walks only: rows filled free from a key already looked up on an earlier page of the same walk. Not counted in `looked_up`, `filled` or `cached`. Absent when zero." }, "steps": { "type": "array", "description": "Present when the request asked for more than one join (`include=engagement,channel`): one report per join, in the order they ran. The top-level numbers are then the page's: rows looked up or filled by any join, and the credits and time of all of them together.", "items": { "type": "object", "description": "One join's report.", "properties": { "include": { "type": "string", "description": "The token that switched the join on.", "example": "profile" }, "implied_by": { "type": "string", "description": "Present when you did not send `include` and another param switched the join on. The join's credits (`extra_credits`) are then part of `credits_used`. Absent when you sent `include` yourself." }, "rows": { "type": "integer", "description": "Rows on the page after any row cap.", "example": 20 }, "looked_up": { "type": "integer", "description": "Rows that needed a lookup (at least one field the join fills was empty).", "example": 20 }, "filled": { "type": "integer", "description": "Rows where at least one field was filled by the join.", "example": 18 }, "cached": { "type": "integer", "description": "Of `filled`, rows filled from the sibling endpoint's cache at no charge.", "example": 0 }, "unfilled": { "type": "integer", "description": "Rows that needed a lookup and were not filled (the lookup failed, was skipped, or had nothing to copy). Their credits are refunded.", "example": 2 }, "credits_held": { "type": "integer", "description": "Credits held up front for the join, on top of the page's own price.", "example": 20 }, "extra_credits": { "type": "integer", "description": "Of `credits_held`, the credits kept: one lookup's price for each distinct key filled from a fresh lookup. The rest was refunded.", "example": 18 }, "ms": { "type": "integer", "description": "Time the join added, in milliseconds.", "example": 2400 }, "cached_page": { "type": "boolean", "description": "True when the whole page was served from cache, so the join cost nothing on this call.", "example": true }, "batches": { "type": "integer", "description": "Joins that look rows up in batches only: how many batch calls were made. Absent on a join that looks rows up one by one." }, "from_earlier_pages": { "type": "integer", "description": "`max_pages`, `max_items` and `max_credits` walks only: rows filled free from a key already looked up on an earlier page of the same walk. Not counted in `looked_up`, `filled` or `cached`. Absent when zero." } } } } } }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/events", "data": { "items": [ { "post": { "id": "3819476484850108", "url": "https://www.facebook.com/events/3819476484850108/", "content": { "text": "Sample comment text (redacted).", "media_urls": null, "thumbnail_url": "https://scontent-lga3-1.xx.fbcdn.net/v/t39.30808-6/756345114_122231390060290000_2227029022001829513_n.jpg?stp=c0.349.1809.863a_dst-jpg_s640x640_tt6&_nc_cat=111&ccb=1-7&_nc_sid=75d36f&_nc_ohc=iWGHi0pKUi8Q7kNvwF2ZFJy&_nc_oc=AdrkxLy37MRknwUEweevINe4QZYdFqNVnbB8gHMPArz54QSUMt6q4FsbsRIHqpIrJXI&_nc_zt=23&_nc_ht=scontent-lga3-1.xx&_nc_gid=ZdGzVcyVO1Z33DETLvfG5w&_nc_ss=78289&oh=00_AQM6zokNAo7pa4qsfJJkHDkjIZmz6R3MF7Xbw-K4mrzuwA&oe=6AC5367B", "duration_seconds": null }, "author": { "username": null, "display_name": null, "avatar_url": null, "verified": null }, "engagement": { "views": 1500, "likes": 155, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-10-17T14:00:00.000Z", "ext": { "published_at_epoch": 1792245600, "event": { "time_text": "Sat, Oct 17 at 10:00 AM EDT", "is_online": false, "is_past": false, "location_name": "Pass A Grille Beach St Pete", "start_timestamp": 1792245600, "interested_count": 1500, "going_count": 155 } } }, "computed": { "engagement_rate": 0.103333, "language": null, "content_category": "other", "estimated_reach": 1800 } }, { "post": { "id": "1566776621097336", "url": "https://www.facebook.com/events/1566776621097336/", "content": { "text": "Sample comment text (redacted).", "media_urls": null, "thumbnail_url": "https://scontent-lga3-1.xx.fbcdn.net/v/t39.30808-6/627975550_122141925152992528_6782463978449409171_n.jpg?stp=c58.0.844.403a_dst-jpg_s640x640_tt6&_nc_cat=111&ccb=1-7&_nc_sid=75d36f&_nc_ohc=o229hHm7iNoQ7kNvwGz9AFU&_nc_oc=AdoQxTT3sam5KmTljWD-OmT9vNbaTTXvzZ9uUBsJvmL8jGeSXa96wH_GyBO_QpNIfKE&_nc_zt=23&_nc_ht=scontent-lga3-1.xx&_nc_gid=ZdGzVcyVO1Z33DETLvfG5w&_nc_ss=78289&oh=00_AQN8sbETUi4MLlefUJlsNNkafkuRUv0DGNfPDdVK_trZEA&oe=6AC527D8", "duration_seconds": null }, "author": { "username": null, "display_name": null, "avatar_url": null, "verified": null }, "engagement": { "views": 11, "likes": 2, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-10-02T12:00:00.000Z", "ext": { "published_at_epoch": 1790942400, "event": { "time_text": "Fri, Oct 2 at 8:00 AM EDT", "is_online": false, "is_past": false, "location_name": "[address redacted] S, St Petersburg, FL 33711-4901, United States", "start_timestamp": 1790942400, "interested_count": 11, "going_count": 2 } } }, "computed": { "engagement_rate": 0.181818, "language": null, "content_category": "other", "estimated_reach": 13 } } ], "next_cursor": "eyJzdGFydF90aW1lIjoxNzkwOTI2MzgyLCJlbmRfdGltZSI6MTc5ODcwMjM4MiwiYnJvd3NlX2N1cnNvciI6IkFib04zQlhfZC1JdldQVWVqNWVSNnBpU0RnNHJSYUY3eHk2TDJYWVlrbGNTVHBDQ0dVQWJsQ2NTazRFOE5Qb2htbGxmMFB1VVlOSk9aMC1nNGNhZE96cFRpSlkwRVAwVVZGc09vcnBHUmhGN1lxQXl1czhxX1R1ZFI1S3ZMR29PdS1PeXJYTXc5UldaTDgwSXh6a2NTeGdIMHV0bFJpcTVXd3FQb2F4T1M0Q05uZjNUa1QwdllmX2FfMHhBSGVFcE9ndzJLUkliRU1ZcEdDa0Y0Nk5LOFhEYTdMb0VyejVsWjV0MDBEbEdUSlNvTWJPR3VRWWp5azVyb1ZaS0VqMjlUUHQxb1VFVVlwOTlzOW5YR3VNZVdtWEdJRm40VDk3dG5rU2ZVYTlteTh0WTR6U1pkcVV3LUVvMDlSQ2lkMnZkUG8tMTRJWDZZamFkWWdWNFpXVlhjazNMWGlwTS1lVUhraXpBck5lUDN3Q1RGSm9UV05zN2VmaHhmdzY5UmRCWDNrSEpuWlRxUGtNWFFsOXd3dDQ0M2RGQXY1V0IteEJKaUN2ODRWN2FnakVXUWRMV1hyTTRKc01FZUs5TVNySFZncDB0aE14aFhFa1k4Z0MwY0trQXQ4SFhuYVBLdWZBVFdrZFgxenA5SXFEY2hNOG41NlRyaTU2RVdmQ1p3Yy1ZTUwtVXJhenF3b3Vwb1NVN3U0dkFaVmJRWFEwQnZQMmVvMDl3N0xsOS0tYXBQQSJ9", "total": null, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiZXlKemRHRnlkRjkwYVcxbElqb3hOemt3T1RJMk16Z3lMQ0psYm1SZmRHbHRaU0k2TVRjNU9EY3dNak00TWl3aVluSnZkM05sWDJOMWNuTnZjaUk2SWtGaWIwNHpRbGhmWkMxSmRsZFFWV1ZxTldWU05uQnBVMFJuTkhKU1lVWTNlSGsyVERKWVdWbHJiR05UVkhCRFEwZFZRV0pzUTJOVGF6UkZPRTVRYjJodGJHeG1NRkIxVlZsT1NrOWFNQzFuTkdOaFpFOTZjRlJwU2xrd1JWQXdWVlpHYzA5dmNuQkhVbWhHTjFseFFYbDFjemh4WDFSMVpGSTFTM1pNUjI5UGRTMVBlWEpZVFhjNVVsZGFURGd3U1hoNmEyTlRlR2RJTUhWMGJGSnBjVFZYZDNGUWIyRjRUMU0wUTA1dVpqTlVhMVF3ZGxsbVgyRmZNSGhCU0dWRmNFOW5kekpMVWtsaVJVMVpjRWREYTBZME5rNUxPRmhFWVRkTWIwVnllalZzV2pWME1EQkViRWRVU2xOdlRXSlBSM1ZSV1dwNWF6VnliMVphUzBWcU1qbFVVSFF4YjFWRlZWbHdPVGx6T1c1WVIzVk5aVmR0V0VkSlJtNDBWRGszZEc1clUyWlZZVGx0ZVRoMFdUUjZVMXBrY1ZWM0xVVnZNRGxTUTJsa01uWmtVRzh0TVRSSldEWlphbUZrV1dkV05GcFhWbGhqYXpOTVdHbHdUUzFsVlVocmFYcEJjazVsVUROM1ExUkdTbTlVVjA1ek4yVm1hSGhtZHpZNVVtUkNXRE5yU0VwdVdsUnhVR3ROV0ZGc09YZDNkRFEwTTJSR1FYWTFWMEl0ZUVKS2FVTjJPRFJXTjJGbmFrVlhVV1JNVjFoeVRUUktjMDFGWlVzNVRWTnlTRlpuY0RCMGFFMTRhRmhGYTFrNFowTXdZMHRyUVhRNFNGaHVZVkJMZFdaQlZGZHJaRmd4ZW5BNVNYRkVZMmhOT0c0MU5sUnlhVFUyUlZkbVExcDNZeTFaVFV3dFZYSmhlbkYzYjNWd2IxTlZOM1UwZGtGYVZtSlJXRkV3UW5aUU1tVnZNRGwzTjB4c09TMHRZWEJRUVNKOSIsImUiOiJmYWNlYm9vay9ldmVudHMiLCJwIjoiY3Vyc29yIn0", "has_more": true, "page_size": 12 }, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/event/details": { "get": { "summary": "Get details for a Facebook event", "description": "Fetches full metadata for a Facebook event. The canonical Post leaves carry the title (`content.text`), the cover image (`content.thumbnail_url`), the permalink and the host line; the event record itself rides `post.ext.event`: `description`, `start_timestamp` and `end_timestamp`, the rendered `time_text` (\"Saturday, August 29, 2026 at 7:00 PM - 9:00 PM PDT\", the only place the event's own timezone appears), `duration_text`, `location_name`, `address`, `city`, `latitude` and `longitude`, `hosts[]` (each with id, name, url and a verification flag), `category`, `ticket_url`, `privacy`, `is_online`, `is_canceled`, `is_past`, and the RSVP counts `interested_count`, `going_count` and `attendance_count`. **Read the RSVP counts from `post.ext.event`, not from `post.engagement`:** an event has no views or likes, so `engagement.views` carries the interested count and `engagement.likes` the going count for archetype compatibility, and `computed.engagement_rate` is derived from those RSVPs rather than from any real engagement.", "tags": [ "facebook" ], "operationId": "get_facebook_event_details", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-socialcrawl-oneOf": [ [ "id", "url" ] ], "parameters": [ { "name": "id", "in": "query", "required": false, "description": "Facebook event ID (numeric). (one of: id, url; at least one required)", "schema": { "type": "string" } }, { "name": "url", "in": "query", "required": false, "description": "Full URL of the event. (one of: id, url; at least one required)", "schema": { "type": "string" }, "example": "https://www.facebook.com/events/4271394179613905/" }, { "name": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 600 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 3600 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/event/details" }, "data": { "type": "object", "description": "Platform-specific response data", "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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "number", "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": [ "number", "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": [ "number", "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", "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "number", "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; discover reads a country from it into `geo.country` (`source: author_location`). 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": [ "number", "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" }, "link_domain": { "type": [ "string", "null" ], "description": "String at post.ext.link_domain" }, "upvote_ratio": { "type": [ "number", "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" ], "enum": [ "video", "short", "live", "channel", "playlist", 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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "enum": [ "image", "video", "carousel", 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": [ "number", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": { "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": { "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": [ "object", "null" ], "description": "Object 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": { "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/profile/posts`, `/v1/instagram/profile/reels`, `/v1/instagram/search/reels`, `/v1/tiktok/profile/videos` 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": [ "object", "null" ], "description": "Object 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", "enum": [ "image", "video" ], "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "number", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "number", "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": [ "number", "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": [ "object", "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": [ "object", "null" ], "description": "Object at post.ext.retweeted_post" }, "quote_count": { "type": [ "number", "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": { "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": [ "object", "null" ], "description": "Object 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": "object", "description": "Object 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": [ "number", "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": [ "object", "null" ], "description": "Object at post.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: post.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.description" } } } }, "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" ], "enum": [ "minute", "hour", "day", "week", "month", "year", 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": [ "number", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "number", "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": [ "object", "null" ], "description": "Object 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": [ "number", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "object", "null" ], "description": "Object at post.ext.dsp_ids", "additionalProperties": { "type": "string", "description": "String 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": "object", "description": "Object at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "object", "description": "Object at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "object", "description": "Object 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": [ "object", "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": [ "object", "null" ], "description": "Object 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": [ "number", "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": "number", "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": [ "object", "null" ], "description": "Object at post.ext.event" }, "trend": { "type": [ "object", "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" }, "numeric_id": { "type": [ "number", "null" ], "description": "Numeric at post.ext.numeric_id" }, "outbound_url": { "type": [ "string", "null" ], "description": "String at post.ext.outbound_url" }, "group": { "type": [ "object", "null" ], "description": "Object at post.ext.group" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "number", "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": [ "number", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "number", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "number", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "enum": [ "target", "other_named_thing", "generic_word", "not_present" ], "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "number", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "number", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "string", "boolean", "null" ], "description": "Union: number | string | boolean" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } } } }, "_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": [ "post" ] }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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 } } } }, "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" } } } } } } }, "/facebook/adlibrary/ad/transcript": { "get": { "summary": "Get a Facebook Ad Library video ad transcript", "description": "Retrieves a transcript for a single Facebook Ad Library video ad. Uses Facebook-provided captions when available, otherwise transcribes the public video URL on demand. Ads without retrievable captions return a 404 RESOURCE_NOT_FOUND, and on-demand transcription can fail transiently (503): both outcomes are free; credits are only deducted when a transcript is returned. On-demand transcription covers videos up to 2 minutes (120 seconds); a longer ad with no captions returns 400 INVALID_REQUEST with `error.details.reason: video_too_long`, `duration_seconds` and `max_seconds`, also free.", "tags": [ "facebook" ], "operationId": "get_facebook_adlibrary_ad_transcript", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "premium", "x-credit-cost": 10, "x-socialcrawl-oneOf": [ [ "id", "url" ] ], "parameters": [ { "name": "id", "in": "query", "required": false, "description": "Facebook Ad Library ad ID. Ad ids rotate as campaigns end, so take a current one from `/v1/facebook/adlibrary/company/ads` rather than reusing an old one. (one of: id, url; at least one required)", "schema": { "type": "string" }, "example": "1126618083054464" }, { "name": "url", "in": "query", "required": false, "description": "Facebook Ad Library URL for the ad. A page URL is rejected with a 400 at 0 credits. (one of: id, url; at least one required)", "schema": { "type": "string" }, "example": "https://www.facebook.com/ads/library?id=1126618083054464" }, { "name": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 2592000 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 2592000 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/adlibrary/ad/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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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 } } } }, "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" } } } } } } }, "/facebook/profile/full": { "get": { "summary": "Facebook profile, recent posts, and computed analytics in one call.", "description": "Fans out to the Facebook 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 Facebook is 3 posts, 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. For Facebook, `author.following` and `author.posts_count` remain null because the profile upstream does not provide those totals.", "tags": [ "facebook" ], "operationId": "get_facebook_profile_full", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 5, "x-socialcrawl-oneOf": [ [ "url" ] ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "Full Facebook profile or page URL. One of the identity params is required. (one of: url; at least one required)", "schema": { "type": "string" }, "example": "https://www.facebook.com/mrbeast" }, { "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 Facebook is 3 posts, 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": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 900 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 3600 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/profile/full", "data": { "profile": { "id": "100044548384499", "username": "mrbeast", "display_name": "MrBeast", "avatar_url": "https://scontent-dfw6-1.xx.fbcdn.net/v/t39.30808-1/351196722_2401743193333639_5070533686922392871_n.png?stp=dst-png&cstp=mx900x900&ctp=s480x480&_nc_cat=1&ccb=1-7&_nc_sid=2d3e12&_nc_ohc=FilSKOcQBRIQ7kNvwFxAT9R&_nc_oc=AdrfaHL3RBJ0bihnyCK04XpVjsJFd0GGeJg-9YgQ6m94rjBhspvhy9AMmYnWKwJpm9s&_nc_zt=24&_nc_ht=scontent-dfw6-1.xx&_nc_gid=Bm1PjPzPGCOO4jaIM8P6pQ&_nc_ss=78289&oh=00_AQMmWJrvITFky5Iuzxlw8Fe7k2CO8YTOyZf5mjPnKaCMnQ&oe=6AC57BC5", "bio": "I want to make the best videos in the world and help as many people as possible :)", "verified": null, "followers": 49000000, "following": null, "posts_count": null, "likes_count": 49277196, "url": "https://www.facebook.com/mrbeast", "private": null, "joined_at": "2015-09-03", "ext": { "public_email": null, "public_phone": null, "business_category": "Reel creator", "website": "http://linktr.ee/beastgames", "cover_url": "https://scontent-dfw6-1.xx.fbcdn.net/v/t39.30808-6/608992901_1437092241119042_2462126656363561737_n.jpg?stp=dst-jpg_tt6&cstp=mx2048x1152&ctp=s2048x1152&_nc_cat=1&ccb=1-7&_nc_sid=cc71e4&_nc_ohc=AWiXaxHSvn8Q7kNvwENmKaY&_nc_oc=AdpDeXic1c5V1CwoMZf-TpRwuahdXc1o1puZ0FYHXl3nklX0Z4dVwz-aYKydypbjS4M&_nc_zt=23&_nc_ht=scontent-dfw6-1.xx&_nc_gid=Bm1PjPzPGCOO4jaIM8P6pQ&_nc_ss=78289&oh=00_AQM_sXq1af2zC4nbhGCzx6PW2WwGSrrLv-D9tYJAPRUzfA&oe=6AC566C5", "page_active": false, "address": null, "price_range": null, "rating": "96% recommend (5,781 reviews)", "rating_count": 5781, "talking_about_count": 7912642, "business_hours": null, "links": [ "https://www.instagram.com/mrbeast", "https://youtube.com/@mrbeast" ], "ad_library_page_id": "1521410468170410", "ad_library_status": "This Page is currently running ads.", "followers_approximate": true } }, "posts": [ { "post": { "id": "1663763328451931", "url": "https://www.facebook.com/reel/1413572895166486/", "content": { "text": "Build A Bridge With Only 5 Boards To Get Your Team Across", "media_urls": "https://scontent-lga3-1.xx.fbcdn.net/v/t15.5256-10/827907112_1654069412822186_1432508272408472120_n.jpg?stp=dst-jpg_p843x403_tt6&_nc_cat=1&ccb=1-7&_nc_sid=d2b52d&_nc_ohc=N_k1cpG6AP4Q7kNvwFrJd4_&_nc_oc=Adrp6aAs1GfUY8_KTyRn4whl2_wYaZGOeIHpOvM-qPo7CjpgbCXcOiMEI4elfblq-Q0&_nc_zt=23&_nc_ht=scontent-lga3-1.xx&_nc_gid=xGbN3PPSFk-vtESLhpT1gQ&_nc_ss=78289&oh=00_AQM04G5xj7SqOso971agoTV5HKmN__AsKfoj1ucVpbqh7Q&oe=6AC57E1D", "thumbnail_url": "https://scontent-lga3-1.xx.fbcdn.net/v/t15.5256-10/827907112_1654069412822186_1432508272408472120_n.jpg?stp=dst-jpg_s960x960_tt6&_nc_cat=1&ccb=1-7&_nc_sid=be8305&_nc_ohc=N_k1cpG6AP4Q7kNvwFrJd4_&_nc_oc=Adrp6aAs1GfUY8_KTyRn4whl2_wYaZGOeIHpOvM-qPo7CjpgbCXcOiMEI4elfblq-Q0&_nc_zt=23&_nc_ht=scontent-lga3-1.xx&_nc_gid=xGbN3PPSFk-vtESLhpT1gQ&_nc_ss=78289&oh=00_AQPaekYrFlXt6wmBy3WpHozPaRi1y0YY3F_bS5eygMc1Jg&oe=6AC57E1D", "duration_seconds": null }, "author": { "username": "mrbeast", "display_name": "MrBeast", "avatar_url": "https://example.com/redacted", "verified": null }, "engagement": { "views": null, "likes": 184531, "comments": 1416, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-10-01T16:00:51.000Z", "ext": { "author_id": "100044548384499", "published_at_epoch": 1790870451, "reaction_counts": [ { "type": "like", "count": 180301 }, { "type": "love", "count": 3366 } ], "feedback_id": "ZmVlZGJhY2s6MTY2Mzc2MzMyODQ1MTkzMQ==" } }, "computed": { "engagement_rate": null, "language": null, "content_category": "other", "estimated_reach": null } }, { "post": { "id": "1662492328579031", "url": "https://www.facebook.com/reel/1446671710687969/", "content": { "text": "Chicken Trap On Deserted Island 🐔", "media_urls": "https://scontent-lga3-1.xx.fbcdn.net/v/t15.5256-10/455247863_876140724434878_519476312287318084_n.jpg?stp=dst-jpg_p843x403_tt6&_nc_cat=1&ccb=1-7&_nc_sid=4eef78&_nc_ohc=oKISaff8ntsQ7kNvwHJGQJL&_nc_oc=Adr1iAmZnz2ESYOw4vGSZ8yNWDQOZc-q1IZ5ff9cC0eUc4amM_K2rm1cklOU8ODLoi0&_nc_zt=23&_nc_ht=scontent-lga3-1.xx&_nc_gid=xGbN3PPSFk-vtESLhpT1gQ&_nc_ss=78289&oh=00_AQM-QHrh0iTDOXrkbuJP7TWwzd0hTF3Gd2ONhrLsyQodmg&oe=6AC5728B", "thumbnail_url": "https://scontent-lga3-1.xx.fbcdn.net/v/t15.5256-10/455247863_876140724434878_519476312287318084_n.jpg?stp=dst-jpg_s960x960_tt6&_nc_cat=1&ccb=1-7&_nc_sid=83a10b&_nc_ohc=oKISaff8ntsQ7kNvwHJGQJL&_nc_oc=Adr1iAmZnz2ESYOw4vGSZ8yNWDQOZc-q1IZ5ff9cC0eUc4amM_K2rm1cklOU8ODLoi0&_nc_zt=23&_nc_ht=scontent-lga3-1.xx&_nc_gid=xGbN3PPSFk-vtESLhpT1gQ&_nc_ss=78289&oh=00_AQMBo0UGhkLCxbPLNqTNRmccu5o4EhwqvmSPC5G0rE8Wzw&oe=6AC5728B", "duration_seconds": null }, "author": { "username": "mrbeast", "display_name": "MrBeast", "avatar_url": "https://example.com/redacted", "verified": null }, "engagement": { "views": null, "likes": 38304, "comments": 1138, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-30T16:01:37.000Z", "ext": { "author_id": "100044548384499", "published_at_epoch": 1790784097, "reaction_counts": [ { "type": "like", "count": 35174 }, { "type": "love", "count": 2618 } ], "feedback_id": "ZmVlZGJhY2s6MTY2MjQ5MjMyODU3OTAzMQ==" } }, "computed": { "engagement_rate": null, "language": null, "content_category": "other", "estimated_reach": null } } ], "computed": { "avg_engagement_rate": null, "avg_engagement_rate_by_followers": 0.002407, "posts_per_week": 18.67, "cadence_window_days": 1.1, "top_post": { "url": "https://www.facebook.com/reel/1413572895166486/", "engagement_total": 185947 }, "format_mix": { "video": 3 } }, "posts_cursor": "Cg8Ob3JnYW5pY19jdXJzb3IJAAACmkFRSFQ0WkRpcVVUTFpaUTBVVTdBZnBtZ1JMdVRtWkpGdTFGdWJoNHRrVlZHakJOUTdXeDY5LTVHWVR0UEpZN01ZZERDSUlJTlE3TVlDR1EwNzdIQ2FKNEdkLXNhd3B1VmNNZG5vSjZZekQ3R0ZmZGxwTC0wdDhVNHUxYVNPSVhCT3NMU1hhYUpaT2xDNy12OGJROWk1OFpSS3h6SUdVZEN3UG1DY3hLeG5VM1MxV01ldVg0N1c5ZXZneXVaMXI5RVhadXh3Y09OejNnM0I5NEh6ajhmVk90WHIzc1Y2WjNOeEFwSE9SbmFIOVhfRzRuSUwwU3NKWTcwX250TC1zcVlmdnhkRVVGaFk2dW9FbVc4T3ptZ3JwSUJQbVhqVlF0OWpWeW5DREtma2hnZ0M0YlcwM0Y3QW1qLVI3U2tnRTMtYmJXY0Q4aUIzWm03Qkc2RTNlSUdPcVRPUFBuVnA4ZVd6M2lYRDUtSmNMTEZReUJ5NVV2VVBhWHd1LVNYYWtuakh2b2pHX0stWThlWE9XSjJPWnVJMF9fbmFNaGg3VEREY0o1bUVQUG9fMTlUM2dDR2hLTjFiYWtxM2pBN09fM1hWTUc1RDl6akUwU1l1SHRYemNLZUhnV3B0cTZsUTJScHlMN19rbEdDdGtJTlJoNnk3Mk1VTTdTRkN0WHlEUTZjcHBMczRCYU9jRDZNdktoZE9VeU1rRDlqdWZIS3BOZ0UzZFBOWHFMeWFKN3lYZzI4dThXQkJxb3VFSTZTMTR0WUZRRE1GNWU4M01RT19QOWpscXVTMjJXbjFTTE5xMU8tSVpMbVgzekxwSWkzZV9laGp4dkxRaDFSZ2p1bE93cEpQR19FSHk0ZlhIMDNWMWp2RnlkS3dvTlZjdw8JYWRfY3Vyc29yDg8PZ2xvYmFsX3Bvc2l0aW9uAgAPBm9mZnNldAIADxBsYXN0X2FkX3Bvc2l0aW9uAv8B", "legs": [ { "endpoint": "/v1/facebook/profile", "status": 200, "credits_used": 1, "latency_ms": 7413, "error": null }, { "endpoint": "/v1/facebook/profile/posts", "status": 200, "credits_used": 1, "latency_ms": 4245, "error": null } ], "_warnings": [ "computed.engagement_rate: author ratio exceeded 1.0 (raw: 1.005657); returned null. A lifetime likes/followers ratio is not a real engagement rate", "computed.avg_engagement_rate is null because no post in this window carries a view count; use computed.avg_engagement_rate_by_followers, which divides likes and comments by the follower count." ] }, "credits_used": 5, "request_id": "req_example000000", "cached": false, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/profile/reels/full": { "get": { "summary": "Facebook profile reels with exact views, likes, comments, and shares merged in, in one call.", "description": "Returns a Facebook page or profile's reels with EXACT per-reel engagement merged in: one call instead of the reels-list → post-stats chain. The plain `/v1/facebook/profile/reels` list only carries a rounded public view count (\"12K\" parsed back to 12000) and no likes, comments, or shares, because Facebook exposes those on the individual reel permalink only. This endpoint fetches the list, then queries each reel's permalink server-side and overwrites the item's `engagement` with the exact figures: `views` (the rounded list value is replaced), `likes`, `comments`, and `shares`. `saves` stays null (Facebook exposes no public save count), and `comments` can be null on a zero-comment reel (a quirk of the permalink upstream). Per-item `ext.engagement_source` is `\"post_detail\"` when the exact figures landed and null when that reel's lookup failed (the item then keeps the honest list values); read `engagement_coverage` before grading, and `_warnings: [\"engagement_partial\"]` flags a partial page. Billing: a flat 5 credits per page of 10 reels (1 credit for the list + 4 for the per-reel enrichment, roughly half the cost of running the chain yourself); if enrichment yields zero coverage the 4-credit premium is refunded automatically. Paginate with `next_cursor`, or pass `limit` (1-50) to have the endpoint walk pages server-side until it has collected that many reels, billed per page consumed.", "tags": [ "facebook" ], "operationId": "get_facebook_profile_reels_full", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "x-credit-cost-min": 5, "x-credit-cost-max": 25, "x-credit-cost-formula": "5 credits per page of 10 reels - 1 for the list and 4 for the per-reel enrichment - which is roughly half what running the list-then-post-stats chain yourself costs. With no `limit` that is one page and a flat 5 credits. With `limit` set the endpoint walks `ceil(limit / 10)` pages, up to 5 for the 50 maximum (25 credits), holds that many up front and refunds every page it did not need. A page whose enrichment yields zero coverage refunds the 4-credit premium automatically, leaving the 1-credit list price", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full URL of the Facebook page or profile. A profile share link (`https://www.facebook.com/share/…`) is accepted.", "schema": { "type": "string" }, "example": "https://www.facebook.com/Meta" }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from a prior response's next_cursor to page deeper.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Return up to this many reels in one call (1-50). The endpoint pages the underlying list server-side until it has collected this many (or runs out), and bills per upstream page consumed (5 credits/page of 10). If the walk hits the internal time budget first, the response carries `_warnings: [\"walk_deadline_reached\"]`, unfetched pages are refunded, and `next_cursor` resumes where it stopped. Omit for a single page.", "schema": { "type": "integer" } }, { "name": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 600 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 3600 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/profile/reels/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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/profile/reels/full", "data": { "items": [ { "post": { "id": "1152729184082957", "url": "https://www.facebook.com/reel/2277713513083702", "content": { "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "media_urls": "https://scontent-lga3-3.xx.fbcdn.net/v/t15.5256-10/808190330_2551818145314526_456542767254010348_n.jpg?stp=dst-jpg_tt6&cstp=mx1080x1920&ctp=p960x960&_nc_cat=108&ccb=1-7&_nc_sid=5fad0e&_nc_ohc=b71k3ILihV8Q7kNvwEm8aR0&_nc_oc=AdrymdXH6mPw8zKAIBnCIjHAfxFgO-8Vm9jcckXe3XRWzUMJSqaPoTvuKBXj1uRo1-U&_nc_zt=23&_nc_ht=scontent-lga3-3.xx&_nc_gid=0K5m6ke5PiWOh76uT2giXg&_nc_ss=78289&oh=00_AQP9MA_vsEbQreBrWe_CsyPsF6NFDvNY_y_EXTwvn8xTbw&oe=6AC5686C", "thumbnail_url": "https://scontent-lga3-3.xx.fbcdn.net/v/t15.5256-10/808190330_2551818145314526_456542767254010348_n.jpg?stp=dst-jpg_tt6&cstp=mx1080x1920&ctp=p960x960&_nc_cat=108&ccb=1-7&_nc_sid=5fad0e&_nc_ohc=b71k3ILihV8Q7kNvwEm8aR0&_nc_oc=AdrymdXH6mPw8zKAIBnCIjHAfxFgO-8Vm9jcckXe3XRWzUMJSqaPoTvuKBXj1uRo1-U&_nc_zt=23&_nc_ht=scontent-lga3-3.xx&_nc_gid=0K5m6ke5PiWOh76uT2giXg&_nc_ss=78289&oh=00_AQP9MA_vsEbQreBrWe_CsyPsF6NFDvNY_y_EXTwvn8xTbw&oe=6AC5686C", "duration_seconds": 74.645 }, "author": { "username": null, "display_name": "Meta", "avatar_url": "https://example.com/avatars/user_8c7327.png", "verified": true }, "engagement": { "views": 28240, "likes": 800, "comments": 218, "shares": 45, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-10-01T16:16:02.000Z", "ext": { "author_id": "user_9cf871", "music": { "id": "28628413730132185", "track_title": "Meta · Original audio" }, "feedback_id": "ZmVlZGJhY2s6MTE1MjcyOTE4NDA4Mjk1Nw==", "engagement_source": "post_detail" } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": 33600 } }, { "post": { "id": "1151655277523681", "url": "https://www.facebook.com/reel/1737837581070505", "content": { "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "media_urls": "https://scontent-lga3-3.xx.fbcdn.net/v/t15.5256-10/796250406_1128825959830539_5799221356349284506_n.jpg?stp=dst-jpg_tt6&cstp=mx1080x1920&ctp=p960x960&_nc_cat=108&ccb=1-7&_nc_sid=5fad0e&_nc_ohc=7-vOzhfiT28Q7kNvwFPfADN&_nc_oc=Adp0t6OM8Q-g1sYhlWa6Hmtfh5YMqfCJh9pFrEv2bPcfgo5-eRkcLIV4vAh1_i-ITUw&_nc_zt=23&_nc_ht=scontent-lga3-3.xx&_nc_gid=0K5m6ke5PiWOh76uT2giXg&_nc_ss=78289&oh=00_AQPnXz2bG4B5NVh_5KiAsKbmp4CYefccAbQVc58FxVJl_Q&oe=6AC58256", "thumbnail_url": "https://scontent-lga3-3.xx.fbcdn.net/v/t15.5256-10/796250406_1128825959830539_5799221356349284506_n.jpg?stp=dst-jpg_tt6&cstp=mx1080x1920&ctp=p960x960&_nc_cat=108&ccb=1-7&_nc_sid=5fad0e&_nc_ohc=7-vOzhfiT28Q7kNvwFPfADN&_nc_oc=Adp0t6OM8Q-g1sYhlWa6Hmtfh5YMqfCJh9pFrEv2bPcfgo5-eRkcLIV4vAh1_i-ITUw&_nc_zt=23&_nc_ht=scontent-lga3-3.xx&_nc_gid=0K5m6ke5PiWOh76uT2giXg&_nc_ss=78289&oh=00_AQPnXz2bG4B5NVh_5KiAsKbmp4CYefccAbQVc58FxVJl_Q&oe=6AC58256", "duration_seconds": 82.666 }, "author": { "username": null, "display_name": "Meta", "avatar_url": "https://example.com/avatars/user_8c7327.png", "verified": true }, "engagement": { "views": 80375, "likes": 2281, "comments": 446, "shares": 190, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-30T16:08:10.000Z", "ext": { "author_id": "user_9cf871", "music": { "id": "38894363146845235", "track_title": "Meta · Original audio" }, "feedback_id": "ZmVlZGJhY2s6MTE1MTY1NTI3NzUyMzY4MQ==", "engagement_source": "post_detail" } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": 96000 } } ], "next_cursor": "scp.eyJ2IjoxLCJxIjp7Im5leHRfcGFnZV9pZCI6IllYQndYMk52Ykd4bFkzUnBiMjQ2Y0daaWFXUXdVVlZ5VlVwVmQwUlJSSEprU0cxVFVEUjRabUpLVEZwV2FtcGFUSHBEZWtOQ09GVklhamwyUkRKVmVtUXhZME5RV0ZsVFZXdHFlamh5WW1GNU9XRkNWVkoyZVVSTFowRm1RV2t6WTFGYU5YWjZZbGhRTm1GTU9HdFJSRkZOZERaMVlrbzFjM3BzIiwiY3Vyc29yIjoiQVFIVGxZaDZIVFFHWHgyaEEzSVN6Nm1vdVY4WHU5THVQZjVDM1l0bXdLblBqZHdMd080d052Mkx0YjdKVUhNbVJQZGUtRUFvSU9BTl9lVE9FbjhWLU8zSXl3In19", "legs": [ { "endpoint": "/v1/facebook/profile/reels", "status": 200, "credits_used": 1, "latency_ms": 2955, "error": null }, { "endpoint": "/v1/facebook/post#fanout", "status": 200, "credits_used": 4, "latency_ms": 7703, "error": null } ], "engagement_coverage": 1, "engagement_fanout_calls": 10, "pages_consumed": 1, "_warnings": [ "limit_truncated_mid_page" ], "dropped": 0 }, "credits_used": 5, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoic2NwLmV5SjJJam94TENKeElqcDdJbTVsZUhSZmNHRm5aVjlwWkNJNklsbFlRbmRZTWs1MllrZDRiRmt6VW5CaU1qUTJZMGRhYVdGWFVYZFZWbFo1VmxWd1ZtUXdVbEpTU0VwclUwY3hWRlZFVWpSYWJVcExWRVp3VjJGdGNHRlVTSEJFWld0T1EwOUdWa2xoYW13eVVrUktWbVZ0VVhoWk1FNVJWMFpzVkZaWGRIRmxhbWg1V1cxR05VOVhSa05XVmtveVpWVlNURm93Um0xUlYydDZXVEZHWVU1WVdqWlpiR2hSVG0xR1RVOUhkRkpTUmtaT1pFUmFNVmxyYnpGak0zQnpJaXdpWTNWeWMyOXlJam9pUVZGSVZHeFphRFpJVkZGSFdIZ3lhRUV6U1ZONk5tMXZkVlk0V0hVNVRIVlFaalZETTFsMGJYZExibEJxWkhkTWQwODBkMDUyTWt4MFlqZEtWVWhOYlZKUVpHVXRSVUZ2U1U5QlRsOWxWRTlGYmpoV0xVOHpTWGwzSW4xOSIsImUiOiJmYWNlYm9vay9wcm9maWxlL3JlZWxzL2Z1bGwiLCJwIjoiY3Vyc29yIn0", "has_more": true, "page_size": 2 }, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/search/posts": { "get": { "summary": "Search Facebook posts by keyword", "description": "Searches public Facebook posts by keyword and returns unified Post items: text, permalink, publish time, like count, comment count, share count, author, and media when Facebook exposes them. About 5 to 7 posts a page. `recent_posts=true` ranks by recency; `start_date` and `end_date` (YYYY-MM-DD) bound the window. Facebook search re-serves posts it has already shown, sometimes from many pages back; the cursor remembers the posts the walk has returned and drops them, so each post comes back once per walk. A page left with nothing new is served empty at 0 credits with the cursor to keep going, so keep calling while `pagination.has_more` is true. When the main source is unavailable, the first page is answered by a second source: the same post fields, with the video file instead of a cover image on video-only posts and no next cursor. A later page or `location_uid` has no second source and returns an error to retry. Forward `pagination.next_cursor` as `cursor`.", "tags": [ "facebook" ], "operationId": "get_facebook_search_posts", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 9, "x-credit-cost-formula": "1 credit per page. 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": "Keyword or phrase to search for.", "schema": { "type": "string" }, "example": "NASA" }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from the previous response.", "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "required": false, "description": "Include posts on or after this date (YYYY-MM-DD).", "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "description": "Include posts on or before this date (YYYY-MM-DD).", "schema": { "type": "string" } }, { "name": "recent_posts", "in": "query", "required": false, "description": "When true, rank by recency instead of relevance.", "schema": { "type": "boolean" } }, { "name": "location_uid", "in": "query", "required": false, "description": "Facebook location id to scope the search.", "schema": { "type": "string" } }, { "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": "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": "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": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 120 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 120 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/search/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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "number", "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": [ "number", "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": [ "number", "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", "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "number", "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; discover reads a country from it into `geo.country` (`source: author_location`). 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": [ "number", "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" }, "link_domain": { "type": [ "string", "null" ], "description": "String at post.ext.link_domain" }, "upvote_ratio": { "type": [ "number", "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" ], "enum": [ "video", "short", "live", "channel", "playlist", 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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "enum": [ "image", "video", "carousel", 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": [ "number", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": { "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": { "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": [ "object", "null" ], "description": "Object 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": { "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/profile/posts`, `/v1/instagram/profile/reels`, `/v1/instagram/search/reels`, `/v1/tiktok/profile/videos` 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": [ "object", "null" ], "description": "Object 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", "enum": [ "image", "video" ], "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "number", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "number", "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": [ "number", "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": [ "object", "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": [ "object", "null" ], "description": "Object at post.ext.retweeted_post" }, "quote_count": { "type": [ "number", "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": { "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": [ "object", "null" ], "description": "Object 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": "object", "description": "Object 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": [ "number", "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": [ "object", "null" ], "description": "Object at post.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: post.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.description" } } } }, "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" ], "enum": [ "minute", "hour", "day", "week", "month", "year", 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": [ "number", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "number", "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": [ "object", "null" ], "description": "Object 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": [ "number", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "object", "null" ], "description": "Object at post.ext.dsp_ids", "additionalProperties": { "type": "string", "description": "String 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": "object", "description": "Object at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "object", "description": "Object at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "object", "description": "Object 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": [ "object", "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": [ "object", "null" ], "description": "Object 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": [ "number", "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": "number", "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": [ "object", "null" ], "description": "Object at post.ext.event" }, "trend": { "type": [ "object", "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" }, "numeric_id": { "type": [ "number", "null" ], "description": "Numeric at post.ext.numeric_id" }, "outbound_url": { "type": [ "string", "null" ], "description": "String at post.ext.outbound_url" }, "group": { "type": [ "object", "null" ], "description": "Object at post.ext.group" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "number", "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": [ "number", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "number", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "number", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "enum": [ "target", "other_named_thing", "generic_word", "not_present" ], "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "number", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "number", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "string", "boolean", "null" ], "description": "Union: number | string | boolean" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } } } } } } }, "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." }, "labels": { "type": "object", "description": "Present when the page's rows were put through labelling: the default labels on a list that carries them, and any labels you named with `label=`. Absent with `judgments=off`. Reports what was judged, what is still pending and what it cost.", "properties": { "presets": { "type": "array", "description": "The labels this report covers.", "items": { "type": "string", "description": "A label name.", "example": "sentiment" } }, "rows": { "type": "integer", "description": "Rows on the page before any drop.", "example": 50 }, "labelled": { "type": "integer", "description": "Rows that carry every label this report covers, freshly judged or from the shared store.", "example": 50 }, "cached": { "type": "integer", "description": "Of `labelled`, rows served entirely from the shared per-row label store.", "example": 0 }, "skipped": { "type": "integer", "description": "Deleted or empty rows. They are never sent for judging or billed and carry `labels: null`.", "example": 0 }, "unjudged": { "type": "integer", "description": "Rows that could not be judged this time (a failure, or past the number of rows one call judges). They carry `labels: null` and are never billed.", "example": 0 }, "dropped": { "type": "integer", "description": "Rows removed by an `exclude=` you asked for. Default labels never drop a row.", "example": 0 }, "dropped_ids": { "type": "array", "description": "Ids of the rows counted in `dropped`.", "items": { "type": "string", "description": "A row id." } }, "extra_credits": { "type": "integer", "description": "Credits the labels added to this call. Always 0 for the default labels.", "example": 0 }, "methodology_version": { "type": "string", "description": "The version of the label questions, so you can tell when they change.", "example": "labels/1" }, "mode": { "type": "string", "enum": [ "default", "requested" ], "description": "`default` when you sent no `label=` and the free default labels ran, `requested` when you named labels.", "example": "default" }, "status": { "type": "string", "enum": [ "complete", "partial", "skipped" ], "description": "`complete`: every judgeable row carries its labels. `partial`: some rows carry `labels: null`, still being judged (see `pending`) or not judged this time. `skipped`: default judging was switched off for this request by a capacity guard, and the page is exactly as it was before labels existed.", "example": "complete" }, "pending": { "type": "integer", "description": "Default labels only: rows still being judged when the page was sent. They ship with `labels: null`, keep being judged afterwards, and your next call for the same page carries them.", "example": 0 }, "pending_ids": { "type": "array", "description": "Ids of the rows counted in `pending`.", "items": { "type": "string", "description": "A row id." } }, "cached_page": { "type": "boolean", "description": "Present and true when the whole page came from the response cache, so this call judged nothing and charged nothing.", "example": true }, "default": { "type": "object", "description": "Present when you named some labels with `label=`: the report of the default labels you did not name, with its own `mode`, `status`, `pending` and `pending_ids`. Absent when you named every default.", "properties": { "presets": { "type": "array", "description": "The labels this report covers.", "items": { "type": "string", "description": "A label name.", "example": "sentiment" } }, "rows": { "type": "integer", "description": "Rows on the page before any drop.", "example": 50 }, "labelled": { "type": "integer", "description": "Rows that carry every label this report covers, freshly judged or from the shared store.", "example": 50 }, "cached": { "type": "integer", "description": "Of `labelled`, rows served entirely from the shared per-row label store.", "example": 0 }, "skipped": { "type": "integer", "description": "Deleted or empty rows. They are never sent for judging or billed and carry `labels: null`.", "example": 0 }, "unjudged": { "type": "integer", "description": "Rows that could not be judged this time (a failure, or past the number of rows one call judges). They carry `labels: null` and are never billed.", "example": 0 }, "dropped": { "type": "integer", "description": "Rows removed by an `exclude=` you asked for. Default labels never drop a row.", "example": 0 }, "dropped_ids": { "type": "array", "description": "Ids of the rows counted in `dropped`.", "items": { "type": "string", "description": "A row id." } }, "extra_credits": { "type": "integer", "description": "Credits the labels added to this call. Always 0 for the default labels.", "example": 0 }, "methodology_version": { "type": "string", "description": "The version of the label questions, so you can tell when they change.", "example": "labels/1" }, "mode": { "type": "string", "enum": [ "default", "requested" ], "description": "`default` when you sent no `label=` and the free default labels ran, `requested` when you named labels.", "example": "default" }, "status": { "type": "string", "enum": [ "complete", "partial", "skipped" ], "description": "`complete`: every judgeable row carries its labels. `partial`: some rows carry `labels: null`, still being judged (see `pending`) or not judged this time. `skipped`: default judging was switched off for this request by a capacity guard, and the page is exactly as it was before labels existed.", "example": "complete" }, "pending": { "type": "integer", "description": "Default labels only: rows still being judged when the page was sent. They ship with `labels: null`, keep being judged afterwards, and your next call for the same page carries them.", "example": 0 }, "pending_ids": { "type": "array", "description": "Ids of the rows counted in `pending`.", "items": { "type": "string", "description": "A row id." } }, "cached_page": { "type": "boolean", "description": "Present and true when the whole page came from the response cache, so this call judged nothing and charged nothing.", "example": true } } } } }, "relevance": { "type": "object", "description": "Present on a list that scores its rows against your query: free by default, or when you send `relevance=score` or `relevance=filter`. Absent with `judgments=off`. Reports what was scored, what a `filter` dropped and what it cost.", "properties": { "mode": { "type": "string", "enum": [ "score", "filter" ], "description": "`score`: rows carry `computed.relevance` and none is dropped. `filter`: rows judged off topic are also dropped.", "example": "score" }, "topic_source": { "type": "string", "enum": [ "query", "relevant_to" ], "description": "Where the topic came from: your search query, or the `relevant_to` you sent.", "example": "query" }, "origin": { "type": "string", "enum": [ "default", "requested" ], "description": "`default` when you sent no `relevance=` (score only, free, never drops or reorders), `requested` when you asked.", "example": "default" }, "rows": { "type": "integer", "description": "Rows on the page before any drop.", "example": 30 }, "scored": { "type": "integer", "description": "Rows that carry a relevance value, freshly judged or from the shared store.", "example": 30 }, "cached": { "type": "integer", "description": "Of `scored`, rows served from the shared store.", "example": 0 }, "kept": { "type": "integer", "description": "Rows left on the page.", "example": 30 }, "dropped": { "type": "integer", "description": "Rows removed by `relevance=filter`.", "example": 0 }, "dropped_ids": { "type": "array", "description": "Ids of the rows counted in `dropped`.", "items": { "type": "string", "description": "A row id." } }, "unjudged": { "type": "integer", "description": "Rows the judgment could not answer for this time. They are kept and carry `relevance: null`.", "example": 0 }, "too_short": { "type": "integer", "description": "Rows with too little text to judge. They are kept.", "example": 0 }, "threshold": { "type": "number", "description": "The probability a row needs to be kept by `relevance=filter`: 0.5, or the `relevance_threshold` you sent.", "example": 0.5 }, "extra_credits": { "type": "integer", "description": "Credits the judgment added to this call. 0 with your query as the topic.", "example": 0 }, "methodology_version": { "type": "string", "description": "The version of the relevance questions.", "example": "relevance/2" }, "status": { "type": "string", "enum": [ "complete", "partial", "skipped" ], "description": "`complete`: every row was scored. `partial`: some rows carry `relevance: null`. `skipped`: default scoring was switched off by a capacity guard.", "example": "complete" }, "pending": { "type": "integer", "description": "Rows still being judged when the page was sent.", "example": 0 }, "pending_ids": { "type": "array", "description": "Ids of the rows counted in `pending`.", "items": { "type": "string", "description": "A row id." } }, "cached_page": { "type": "boolean", "description": "Present and true when the whole page came from the response cache, so nothing was judged or charged." }, "unjudged_dropped": { "type": "object", "description": "Present on a merged multi-platform search under `relevance=filter`: rows dropped because they could not be judged in time, counted per platform." }, "context_hash": { "type": "string", "description": "Present on a leg of a merged multi-platform search: a hash of the topic judged." }, "fresh_ids": { "type": "array", "description": "Present on a leg of a merged multi-platform search: the rows judged afresh on this leg.", "items": { "type": "string", "description": "A row id." } } } }, "walk": { "type": "object", "description": "Present when the request sent a row-walk param (`max_pages` above 1, `max_items`, `max_credits`, a row filter, `sort_rows` or `seen`). What the walk did across the pages it fetched. Each page is billed as one call, and its charge is recorded under its own request id.", "properties": { "pages": { "type": "integer", "description": "Pages fetched.", "example": 3 }, "stopped": { "type": "string", "enum": [ "end", "max_pages", "max_items", "max_credits", "time_budget", "page_error" ], "description": "Why the walk stopped. `end`: the list ran out. `max_pages`, `max_items` or `max_credits`: the limit you set was reached. `time_budget`: the request's time budget ran low. `page_error`: a later page failed. Unless it is `end`, `pagination.next_cursor` continues from where the walk stopped.", "example": "max_pages" }, "rows_fetched": { "type": "integer", "description": "Rows read across every page, before any filter.", "example": 60 }, "rows_returned": { "type": "integer", "description": "Rows in `data.items`.", "example": 41 }, "discarded": { "type": "object", "description": "Present when you sent a row filter. Rows the filters removed, counted once each under the first filter they failed. A row a filter cannot verify (no view count, no date, no country) is discarded.", "properties": { "views_below_min": { "type": "integer", "description": "Rows with fewer views than `min_views`." }, "views_unknown": { "type": "integer", "description": "Rows with no view count, when `min_views` was sent." }, "older_than_max_age": { "type": "integer", "description": "Rows published before the `max_age_days` window." }, "date_unknown": { "type": "integer", "description": "Rows with no publish date, when `max_age_days` was sent." }, "country_not_included": { "type": "integer", "description": "Rows registered to a country that is not in `country`." }, "country_unknown": { "type": "integer", "description": "Rows with no country, when `country` was sent." }, "country_excluded": { "type": "integer", "description": "Rows registered to a country listed in `exclude_country`." } } }, "repeats": { "type": "integer", "description": "Present when you sent `seen`: rows removed because your account already received them under that id." }, "duplicates": { "type": "integer", "description": "Present when above zero: rows a later page repeated from an earlier page of the same walk, kept once." }, "credits": { "type": "object", "description": "What the pages cost.", "properties": { "pages": { "type": "integer", "description": "Credits charged for the pages walked, before refunds." }, "refunded": { "type": "integer", "description": "Credits refunded across the pages." } } }, "request_ids": { "type": "array", "description": "The request id of each page walked. Each is its own entry in `GET /v1/credits/transactions`.", "items": { "type": "string", "description": "A row id." } } } }, "estimate": { "type": "object", "description": "Present only on a dry run (`dry_run=1`). A dry run charges 0 credits, fetches nothing and returns `data.valid`, `data.normalized_params` and this `estimate` in place of the usual rows. An invalid request is the normal free 400 instead.", "properties": { "kind": { "type": "string", "description": "Always `estimate`.", "example": "estimate" }, "version": { "type": "integer", "description": "The version of this estimate shape.", "example": 1 }, "id": { "type": "string", "description": "The endpoint, as `platform/resource`." }, "method": { "type": "string", "description": "The HTTP method.", "example": "GET" }, "valid": { "type": "boolean", "description": "True when the request would pass every check made before billing.", "example": true }, "hold": { "type": "integer", "description": "Exactly what the router would deduct up front for this request." }, "expected_min": { "type": "integer", "description": "The least a successful call settles at." }, "expected_max": { "type": "integer", "description": "The most a call can settle at. Unused hold is refunded." }, "unit": { "type": "string", "description": "Always `credits`.", "example": "credits" }, "pricing": { "type": "string", "enum": [ "flat", "metered" ], "description": "`flat`: the same price every call. `metered`: the price depends on the work done, and unused hold is refunded.", "example": "flat" }, "formula": { "type": "string", "description": "How the price is worked out, in words." }, "levers": { "type": "array", "description": "Params that change the price, each with the hold for the same request with that one change.", "items": { "type": "object", "description": "One lever.", "properties": { "param": { "type": "string", "description": "The param to change." }, "hold": { "type": "integer", "description": "The hold for the same request with this one change." }, "effect": { "type": "string", "description": "What the change does." } } } }, "cached_likely": { "type": "boolean", "description": "Always false: a dry run does not read the cache.", "example": false }, "normalized_params": { "type": "object", "description": "The params the router prices, after its own normalisation." }, "notes": { "type": "array", "description": "Plain-English notes about this quote.", "items": { "type": "string", "description": "One note." } }, "warnings": { "type": "array", "description": "Notices about the quote, such as a page count that had to be assumed.", "items": { "type": "string", "description": "One notice." } }, "rows_expected": { "type": "integer", "description": "Judged lists only: the most rows one call judges on this endpoint." }, "rows_cached": { "type": "integer", "description": "Judged lists only: rows already judged and free. 0 on a dry run, which sees no rows." }, "label_credits_min": { "type": "integer", "description": "Judged lists only: the least the paid labels add. 0 on a dry run, which sees no rows." }, "label_credits_max": { "type": "integer", "description": "Judged lists only: the most the paid labels can add. 0 when you asked for no paid label." }, "base_credits": { "type": "integer", "description": "Judged lists only: the call's price without the label and relevance holds." } } }, "held_back": { "type": "object", "description": "Present when you sent `fit=goal` with a `goal` and at least one block of the page was not needed for it. The held rows (or fields) stay in place as stubs of `{ id, held: true }`; this block lists them.", "properties": { "ids": { "type": "array", "description": "Ids of the rows or fields that were held back.", "items": { "type": "string", "description": "A row id." } }, "recall": { "type": "string", "description": "A recall id for the full page, which re-reads it from cache at no extra charge.", "example": "fit_3f9a1c0b7d2e4a58" } } }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/search/posts", "data": { "items": [ { "post": { "id": "1630814579084209", "url": "https://www.facebook.com/user_fdd804/posts/pfbid0q7cqgiYUeLm7eSMW31uyyMP3adZvzXoiF9hkeaNDgDaMZZBXy27kTyTmR7SMb73Cl", "content": { "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "media_urls": "https://scontent-lax7-1.xx.fbcdn.net/v/t39.30808-6/825292453_1630814539084213_2872114838152150161_n.jpg?_nc_cat=105&ccb=1-7&_nc_sid=127cfc&_nc_ohc=3J82GAiQ7FYQ7kNvwGo55W_&_nc_oc=Adq8_DrhGjf5KgZ7pNtOQn31HxECqV1u1PGwLnnoi94ld8qT26KFJaQF6-Mypr2IGag&_nc_zt=23&_nc_ht=scontent-lax7-1.xx&_nc_gid=3jPBS4PzF6TTODG5vj_OpA&_nc_ss=70289&oh=00_AQN5yohVYYM2TTsnUincGgnCqMk6wXTN73euUypWyZUJdw&oe=6AC59468", "thumbnail_url": null, "duration_seconds": null }, "author": { "username": null, "display_name": "user_60bab3", "avatar_url": null, "verified": null }, "engagement": { "views": null, "likes": 200, "comments": 124, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-27T16:30:14.000Z", "ext": { "author_id": "user_c1613a", "published_at_epoch": 1790526614, "reaction_counts": [ { "type": "like", "count": 151 }, { "type": "love", "count": 23 } ] } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": null, "relevance": { "p": 0.92, "sense": "target", "depth": 2.09, "spam": 0.1 }, "labels": { "sponsored": { "p": 0.02, "disclosed": false, "undisclosed": false, "brand": null }, "intent": { "label": "news_or_discussion", "confidence": 0.93, "buyer": false, "seller": 0.14, "fits_offer": null, "urgency": 2.01 }, "niche": { "label": "education_science", "confidence": 0.75, "taxonomy": "sc-niche-v1" } } } }, { "post": { "id": "122266274942144344", "url": "https://www.facebook.com/permalink.php?story_fbid=pfbid02cmkDNEzjb67Gv1SfV3uDXrXGTGj5mE6puGrxLnezK7Q25WAY7jLtrYJa3yLYV6wZl&id=61554330324919", "content": { "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "media_urls": "https://scontent-lax3-1.xx.fbcdn.net/v/t39.30808-6/814926046_122266274918144344_5058024073916801374_n.jpg?_nc_cat=109&ccb=1-7&_nc_sid=833d8c&_nc_ohc=PuXZNRQG-goQ7kNvwHNsfcW&_nc_oc=AdpMwNkVvNOkBAyzw7ucLyc0TkKktlITrAOfNhj-0NEDkrdaZs9fWz7zx80_a--LKrk&_nc_zt=23&_nc_ht=scontent-lax3-1.xx&_nc_gid=3jPBS4PzF6TTODG5vj_OpA&_nc_ss=70289&oh=00_AQPOK7Kq7VT4NGYuGTnCZw76BtLjGWgDvKF2pBA4Rz0HGQ&oe=6AC56370", "thumbnail_url": null, "duration_seconds": null }, "author": { "username": null, "display_name": "user_09a3ea", "avatar_url": null, "verified": null }, "engagement": { "views": null, "likes": 1198, "comments": 978, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-09-18T13:50:22.000Z", "ext": { "author_id": "user_e573be", "published_at_epoch": 1789739422, "reaction_counts": [ { "type": "like", "count": 782 }, { "type": "haha", "count": 282 } ] } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": null, "relevance": { "p": 0.84, "sense": "not_present", "depth": 1.29, "spam": 0.09 }, "labels": { "sponsored": { "p": 0.02, "disclosed": false, "undisclosed": false, "brand": null }, "intent": { "label": "news_or_discussion", "confidence": 1, "buyer": false, "seller": 0.06, "fits_offer": null, "urgency": 0 }, "niche": { "label": "education_science", "confidence": 0.92, "taxonomy": "sc-niche-v1" } } } } ], "next_cursor": "{\"page_number\": 0, \"flow_cursors_serialized\": {\"INTERNAL_DEBUG_MODULE\": \"{}\", \"SEARCH_CONTROLS_INTERCEPT\": \"{}\", \"INTEGRITY\": \"{}\", \"SHORTCUT_DEEP_DIVE\": \"{}\", \"SPELLER\": \"{}\", \"HASHTAG_HEADER\": \"{}\", \"HASHTAG_CACHED_CONTENT\": \"{}\", \"POSTS_TAB_UNICORN_CACHE\": \"{}\", \"POSTS_TAB\": \"{\\\"has_more_results\\\": true, \\\"browse_cursor_serialized\\\": \\\"AbptJB-mwA1REwJLKlGrul5E-htGiRpc28aOMe6LTBx4FGo7fKpZxNwh1mzEA_abZbnIg1T7WpnkeDhZDeu95NfCK-t7MCVvEtLOw7bZdqrJkW7zCILrUR_RrFVTalP_wAwEnhMewmR0llhKJlEXSHCF-mYKRyZoItkEPCxlcV9QG6CEMOpWS7TJtiS9JzWXR0ruB9qDWyYwSTxMf6ys7M4260u4E8_XVXmmRE7uBvQs3meGis3CdGYG5dnKkmkQRgV4ZQGsRfWhOAmRFY5juCCPXeL1p4AvePLeIG4BN97fkZ1DeKs8MM8lR7KOW0hwPLqI8TFsbd4TzAXbpsGxbk7sV13yQCJbxR8St6dO3YTeRYVt8V5YMFM2dqkcKnn4TIqiYf2lGFotYA8--0fY2YSn8KpQfBoupRzpnsKoF1Qx3QkbOrlciwV8HfbMZsYpQ06p4DeDQ5eaZYjuP9rMEyXs0vGaXWcYmo0B3hcWapl9E5cN_BsygwFIjNWBEb4sVaoQ8yoBcc68EntflYfGRkK_ClIXPVKyaVNz5UvkFG5p_mdQcSYK8T20bEnRLlq_0rQSkTUe4kJ8mhGTHiowK6JCxasi3EBTJzI_CquYmMBDjUqtmyYWfEb8fRxA7XXSR18\\\", \\\"processed_unicorn_ids\\\": [], \\\"is_end_of_serp\\\": false}\", \"PARALLEL_FETCH_NOOP\": \"{}\"}, \"result_ids_shown\": [], \"unit_id_logging_fields\": {\"num_total_modules\": 2, \"num_total_results\": 5, \"num_total_vertical_results\": 5}, \"entity_ids_shown_by_type\": {}, \"processed_unicorn_ids\": [], \"completed_flows\": [\"INTERNAL_DEBUG_MODULE\", \"SEARCH_CONTROLS_INTERCEPT\", \"INTEGRITY\", \"SHORTCUT_DEEP_DIVE\", \"SPELLER\", \"HASHTAG_HEADER\", \"HASHTAG_CACHED_CONTENT\", \"POSTS_TAB_UNICORN_CACHE\"], \"custom_cursors_serialized\": {}}", "total": null, "relevance": { "mode": "score", "topic_source": "query", "rows": 5, "scored": 5, "cached": 0, "kept": 5, "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": 5, "labelled": 5, "cached": 0, "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.eyJ2IjoyLCJjIjoie1wicGFnZV9udW1iZXJcIjogMCwgXCJmbG93X2N1cnNvcnNfc2VyaWFsaXplZFwiOiB7XCJJTlRFUk5BTF9ERUJVR19NT0RVTEVcIjogXCJ7fVwiLCBcIlNFQVJDSF9DT05UUk9MU19JTlRFUkNFUFRcIjogXCJ7fVwiLCBcIklOVEVHUklUWVwiOiBcInt9XCIsIFwiU0hPUlRDVVRfREVFUF9ESVZFXCI6IFwie31cIiwgXCJTUEVMTEVSXCI6IFwie31cIiwgXCJIQVNIVEFHX0hFQURFUlwiOiBcInt9XCIsIFwiSEFTSFRBR19DQUNIRURfQ09OVEVOVFwiOiBcInt9XCIsIFwiUE9TVFNfVEFCX1VOSUNPUk5fQ0FDSEVcIjogXCJ7fVwiLCBcIlBPU1RTX1RBQlwiOiBcIntcXFwiaGFzX21vcmVfcmVzdWx0c1xcXCI6IHRydWUsIFxcXCJicm93c2VfY3Vyc29yX3NlcmlhbGl6ZWRcXFwiOiBcXFwiQWJwdEpCLW13QTFSRXdKTEtsR3J1bDVFLWh0R2lScGMyOGFPTWU2TFRCeDRGR283ZktwWnhOd2gxbXpFQV9hYlpibklnMVQ3V3Bua2VEaFpEZXU5NU5mQ0stdDdNQ1Z2RXRMT3c3YlpkcXJKa1c3ekNJTHJVUl9SckZWVGFsUF93QXdFbmhNZXdtUjBsbGhLSmxFWFNIQ0YtbVlLUnlab0l0a0VQQ3hsY1Y5UUc2Q0VNT3BXUzdUSnRpUzlKeldYUjBydUI5cURXeVl3U1R4TWY2eXM3TTQyNjB1NEU4X1hWWG1tUkU3dUJ2UXMzbWVHaXMzQ2RHWUc1ZG5La21rUVJnVjRaUUdzUmZXaE9BbVJGWTVqdUNDUFhlTDFwNEF2ZVBMZUlHNEJOOTdma1oxRGVLczhNTThsUjdLT1cwaHdQTHFJOFRGc2JkNFR6QVhicHNHeGJrN3NWMTN5UUNKYnhSOFN0NmRPM1lUZVJZVnQ4VjVZTUZNMmRxa2NLbm40VElxaVlmMmxHRm90WUE4LS0wZlkyWVNuOEtwUWZCb3VwUnpwbnNLb0YxUXgzUWtiT3JsY2l3VjhIZmJNWnNZcFEwNnA0RGVEUTVlYVpZanVQOXJNRXlYczB2R2FYV2NZbW8wQjNoY1dhcGw5RTVjTl9Cc3lnd0ZJak5XQkViNHNWYW9ROHlvQmNjNjhFbnRmbFlmR1JrS19DbElYUFZLeWFWTno1VXZrRkc1cF9tZFFjU1lLOFQyMGJFblJMbHFfMHJRU2tUVWU0a0o4bWhHVEhpb3dLNkpDeGFzaTNFQlRKeklfQ3F1WW1NQkRqVXF0bXlZV2ZFYjhmUnhBN1hYU1IxOFxcXCIsIFxcXCJwcm9jZXNzZWRfdW5pY29ybl9pZHNcXFwiOiBbXSwgXFxcImlzX2VuZF9vZl9zZXJwXFxcIjogZmFsc2V9XCIsIFwiUEFSQUxMRUxfRkVUQ0hfTk9PUFwiOiBcInt9XCJ9LCBcInJlc3VsdF9pZHNfc2hvd25cIjogW10sIFwidW5pdF9pZF9sb2dnaW5nX2ZpZWxkc1wiOiB7XCJudW1fdG90YWxfbW9kdWxlc1wiOiAyLCBcIm51bV90b3RhbF9yZXN1bHRzXCI6IDUsIFwibnVtX3RvdGFsX3ZlcnRpY2FsX3Jlc3VsdHNcIjogNX0sIFwiZW50aXR5X2lkc19zaG93bl9ieV90eXBlXCI6IHt9LCBcInByb2Nlc3NlZF91bmljb3JuX2lkc1wiOiBbXSwgXCJjb21wbGV0ZWRfZmxvd3NcIjogW1wiSU5URVJOQUxfREVCVUdfTU9EVUxFXCIsIFwiU0VBUkNIX0NPTlRST0xTX0lOVEVSQ0VQVFwiLCBcIklOVEVHUklUWVwiLCBcIlNIT1JUQ1VUX0RFRVBfRElWRVwiLCBcIlNQRUxMRVJcIiwgXCJIQVNIVEFHX0hFQURFUlwiLCBcIkhBU0hUQUdfQ0FDSEVEX0NPTlRFTlRcIiwgXCJQT1NUU19UQUJfVU5JQ09STl9DQUNIRVwiXSwgXCJjdXN0b21fY3Vyc29yc19zZXJpYWxpemVkXCI6IHt9fSIsImUiOiJmYWNlYm9vay9zZWFyY2gvcG9zdHMiLCJwIjoiY3Vyc29yIn0", "has_more": true, "page_size": 5 }, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/search/pages": { "get": { "summary": "Search Facebook pages by keyword", "description": "Searches public Facebook pages by keyword and returns unified Author items: page id, display name, permalink, avatar, and verified flag. Facebook's search card carries no follower count, bio, page likes or creation date, so on a plain call `author.followers`, `author.bio`, `author.likes_count` and `author.joined_at` are null on every row. Send `include=details` and every page is joined, in the same call, to the page lookup for its `author.url`: the follower count, the bio, the page likes and the creation date land on each row. The page id, name, permalink and avatar the search row carries are never replaced. Cost: 1 credit for the page plus 1 credit per page filled from a fresh lookup (at most 10 a page, so 11 credits at most); rows already in cache are free, rows that could not be filled are refunded, and a repeat of the same call within the cache window is 0 credits. Time: `include=details` adds 3 to 10 seconds on a fresh page (the lookups run in parallel and the call waits for the slowest, never more than 12 seconds) and nothing when the rows are already cached. The response carries a `hydration` block itemising rows, lookups, cache hits, credits and milliseconds. About 7 pages on the first page and 8 or 9 on later ones. Forward `pagination.next_cursor` as `cursor`.", "tags": [ "facebook" ], "operationId": "get_facebook_search_pages", "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=details holds 1 credit per page (at most 10) and keeps only the rows filled from a fresh lookup, so a page is at most 11 credits; rows served from cache are free, unfilled rows 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": "query", "in": "query", "required": true, "description": "Keyword or phrase to search for.", "schema": { "type": "string" }, "example": "NASA" }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from the previous response.", "schema": { "type": "string" } }, { "name": "location_uid", "in": "query", "required": false, "description": "Facebook location id to scope the search.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Set to `details` (one token only) to fill `author.followers`, `author.bio`, `author.likes_count` and `author.joined_at` on every page in this one call. Holds 1 credit per page (at most 10) and keeps only the rows filled from a fresh lookup: rows already in cache and rows the lookup cannot fill are refunded, so a page is never more than 11 credits. The join takes 3 to 10 seconds on a fresh page, never more than 12, and nothing when the rows are already cached; read `data.hydration` for the rows, the credits held and kept, and the time. Without it the call is unchanged.", "schema": { "type": "string", "enum": [ "details" ] } }, { "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": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 120 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 120 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/search/pages" }, "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": [ "number", "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": [ "number", "null" ], "description": "Number of accounts followed" }, "posts_count": { "type": [ "number", "null" ], "description": "Total number of posts / videos / tracks / episodes" }, "likes_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at author.ext.employee_count_range.start" }, "end": { "type": [ "number", "null" ], "description": "Numeric at author.ext.employee_count_range.end" } } }, "founded_year": { "type": [ "number", "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": [ "object", "null" ], "description": "Object at author.ext.headquarters" }, "locations": { "type": [ "array", "null" ], "description": "Array at author.ext.locations", "items": { "description": "Leaf at author.ext.locations" } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at author.ext.hashtags", "items": { "description": "Leaf at author.ext.hashtags" } }, "funding": { "type": [ "object", "null" ], "description": "Object 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": [ "number", "null" ], "description": "Numeric at author.ext.rating_count" }, "talking_about_count": { "type": [ "number", "null" ], "description": "Numeric at author.ext.talking_about_count" }, "business_hours": { "type": [ "array", "null" ], "description": "Array at author.ext.business_hours", "items": { "description": "Leaf at author.ext.business_hours" } }, "links": { "type": [ "array", "null" ], "description": "Array at author.ext.links", "items": { "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" ], "enum": [ "app", "web", 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": [ "number", "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": [ "object", "null" ], "description": "Object 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": [ "object", "null" ], "description": "Object at author.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: author.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at author.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at author.ext.localizations.*.description" } } } }, "monthly_listeners": { "type": [ "number", "null" ], "description": "Numeric at author.ext.monthly_listeners" }, "total_ratings": { "type": [ "number", "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": [ "number", "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": "object", "description": "Object at author.ext.rules" } }, "weekly_active_users": { "type": [ "number", "null" ], "description": "Numeric at author.ext.weekly_active_users" }, "weekly_contributions": { "type": [ "number", "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": [ "number", "null" ], "description": "Numeric at author.ext.post_karma" }, "comment_karma": { "type": [ "number", "null" ], "description": "Numeric at author.ext.comment_karma" }, "awardee_karma": { "type": [ "number", "null" ], "description": "Numeric at author.ext.awardee_karma" }, "trophy_count": { "type": [ "number", "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": { "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": [ "object", "null" ], "description": "Object at author.ext.group" }, "search_hit": { "type": [ "object", "null" ], "description": "Nested object: author.ext.search_hit", "properties": { "match": { "type": [ "string", "null" ], "enum": [ "group_page", "post_in_group", "channel_page", "post_in_channel", 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": [ "number", "null" ], "description": "Numeric at author.ext.visitors_today" }, "visitors_total": { "type": [ "number", "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." }, "walk": { "type": "object", "description": "Present when the request sent a row-walk param (`max_pages` above 1, `max_items`, `max_credits`, a row filter, `sort_rows` or `seen`). What the walk did across the pages it fetched. Each page is billed as one call, and its charge is recorded under its own request id.", "properties": { "pages": { "type": "integer", "description": "Pages fetched.", "example": 3 }, "stopped": { "type": "string", "enum": [ "end", "max_pages", "max_items", "max_credits", "time_budget", "page_error" ], "description": "Why the walk stopped. `end`: the list ran out. `max_pages`, `max_items` or `max_credits`: the limit you set was reached. `time_budget`: the request's time budget ran low. `page_error`: a later page failed. Unless it is `end`, `pagination.next_cursor` continues from where the walk stopped.", "example": "max_pages" }, "rows_fetched": { "type": "integer", "description": "Rows read across every page, before any filter.", "example": 60 }, "rows_returned": { "type": "integer", "description": "Rows in `data.items`.", "example": 41 }, "discarded": { "type": "object", "description": "Present when you sent a row filter. Rows the filters removed, counted once each under the first filter they failed. A row a filter cannot verify (no view count, no date, no country) is discarded.", "properties": { "views_below_min": { "type": "integer", "description": "Rows with fewer views than `min_views`." }, "views_unknown": { "type": "integer", "description": "Rows with no view count, when `min_views` was sent." }, "older_than_max_age": { "type": "integer", "description": "Rows published before the `max_age_days` window." }, "date_unknown": { "type": "integer", "description": "Rows with no publish date, when `max_age_days` was sent." }, "country_not_included": { "type": "integer", "description": "Rows registered to a country that is not in `country`." }, "country_unknown": { "type": "integer", "description": "Rows with no country, when `country` was sent." }, "country_excluded": { "type": "integer", "description": "Rows registered to a country listed in `exclude_country`." } } }, "repeats": { "type": "integer", "description": "Present when you sent `seen`: rows removed because your account already received them under that id." }, "duplicates": { "type": "integer", "description": "Present when above zero: rows a later page repeated from an earlier page of the same walk, kept once." }, "credits": { "type": "object", "description": "What the pages cost.", "properties": { "pages": { "type": "integer", "description": "Credits charged for the pages walked, before refunds." }, "refunded": { "type": "integer", "description": "Credits refunded across the pages." } } }, "request_ids": { "type": "array", "description": "The request id of each page walked. Each is its own entry in `GET /v1/credits/transactions`.", "items": { "type": "string", "description": "A row id." } } } }, "hydration": { "type": "object", "description": "Present when the request asked for a row join with `include=`, or sent a param that implies one. What the join did and what it cost. On a multi-page walk it sums every page. A join that always runs for free is left out.", "properties": { "include": { "type": "string", "description": "The token that switched the join on.", "example": "profile" }, "implied_by": { "type": "string", "description": "Present when you did not send `include` and another param switched the join on. The join's credits (`extra_credits`) are then part of `credits_used`. Absent when you sent `include` yourself." }, "rows": { "type": "integer", "description": "Rows on the page after any row cap.", "example": 20 }, "looked_up": { "type": "integer", "description": "Rows that needed a lookup (at least one field the join fills was empty).", "example": 20 }, "filled": { "type": "integer", "description": "Rows where at least one field was filled by the join.", "example": 18 }, "cached": { "type": "integer", "description": "Of `filled`, rows filled from the sibling endpoint's cache at no charge.", "example": 0 }, "unfilled": { "type": "integer", "description": "Rows that needed a lookup and were not filled (the lookup failed, was skipped, or had nothing to copy). Their credits are refunded.", "example": 2 }, "credits_held": { "type": "integer", "description": "Credits held up front for the join, on top of the page's own price.", "example": 20 }, "extra_credits": { "type": "integer", "description": "Of `credits_held`, the credits kept: one lookup's price for each distinct key filled from a fresh lookup. The rest was refunded.", "example": 18 }, "ms": { "type": "integer", "description": "Time the join added, in milliseconds.", "example": 2400 }, "cached_page": { "type": "boolean", "description": "True when the whole page was served from cache, so the join cost nothing on this call.", "example": true }, "batches": { "type": "integer", "description": "Joins that look rows up in batches only: how many batch calls were made. Absent on a join that looks rows up one by one." }, "from_earlier_pages": { "type": "integer", "description": "`max_pages`, `max_items` and `max_credits` walks only: rows filled free from a key already looked up on an earlier page of the same walk. Not counted in `looked_up`, `filled` or `cached`. Absent when zero." }, "steps": { "type": "array", "description": "Present when the request asked for more than one join (`include=engagement,channel`): one report per join, in the order they ran. The top-level numbers are then the page's: rows looked up or filled by any join, and the credits and time of all of them together.", "items": { "type": "object", "description": "One join's report.", "properties": { "include": { "type": "string", "description": "The token that switched the join on.", "example": "profile" }, "implied_by": { "type": "string", "description": "Present when you did not send `include` and another param switched the join on. The join's credits (`extra_credits`) are then part of `credits_used`. Absent when you sent `include` yourself." }, "rows": { "type": "integer", "description": "Rows on the page after any row cap.", "example": 20 }, "looked_up": { "type": "integer", "description": "Rows that needed a lookup (at least one field the join fills was empty).", "example": 20 }, "filled": { "type": "integer", "description": "Rows where at least one field was filled by the join.", "example": 18 }, "cached": { "type": "integer", "description": "Of `filled`, rows filled from the sibling endpoint's cache at no charge.", "example": 0 }, "unfilled": { "type": "integer", "description": "Rows that needed a lookup and were not filled (the lookup failed, was skipped, or had nothing to copy). Their credits are refunded.", "example": 2 }, "credits_held": { "type": "integer", "description": "Credits held up front for the join, on top of the page's own price.", "example": 20 }, "extra_credits": { "type": "integer", "description": "Of `credits_held`, the credits kept: one lookup's price for each distinct key filled from a fresh lookup. The rest was refunded.", "example": 18 }, "ms": { "type": "integer", "description": "Time the join added, in milliseconds.", "example": 2400 }, "cached_page": { "type": "boolean", "description": "True when the whole page was served from cache, so the join cost nothing on this call.", "example": true }, "batches": { "type": "integer", "description": "Joins that look rows up in batches only: how many batch calls were made. Absent on a join that looks rows up one by one." }, "from_earlier_pages": { "type": "integer", "description": "`max_pages`, `max_items` and `max_credits` walks only: rows filled free from a key already looked up on an earlier page of the same walk. Not counted in `looked_up`, `filled` or `cached`. Absent when zero." } } } } } }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/search/pages", "data": { "items": [ { "author": { "id": "user_9e601d", "username": "user_06552e", "display_name": "user_4da615", "avatar_url": "https://example.com/avatars/user_293b8b.png", "bio": null, "verified": true, "followers": null, "following": null, "posts_count": null, "likes_count": null, "url": "https://example.com/user_826270", "private": null, "joined_at": null } }, { "author": { "id": "user_f0f00a", "username": "user_197696", "display_name": "user_dc15e2", "avatar_url": "https://example.com/avatars/user_4a0082.png", "bio": null, "verified": true, "followers": null, "following": null, "posts_count": null, "likes_count": null, "url": "https://example.com/user_36cfd4", "private": null, "joined_at": null } } ], "next_cursor": "{\"page_number\": 0, \"flow_cursors_serialized\": {\"INTERNAL_DEBUG_MODULE\": \"{}\", \"SEARCH_CONTROLS_INTERCEPT\": \"{}\", \"INTEGRITY\": \"{\\\"has_more_results\\\":false,\\\"processed_unicorn_ids\\\":[],\\\"is_end_of_serp\\\":false}\", \"SPELLER\": \"{}\", \"PAGES_TAB\": \"{\\\"has_more_results\\\": true, \\\"browse_cursor_serialized\\\": \\\"AbqxAahmcx3cc4Y7KYnlA9aWhvxtDhIaVO71jBE3ezPvA8BTckSxhagDuSlyKbefJXZ7cd1N7Gk77kq0VfMstgAqrCAAt9p2tqLXLDSVe-A1g9h315ZhiahhkqA31Tf5rMx40O_0-51muajDlSHF0Pu3svmhygILG9sN3I2l7S4J4h8H3P-l6k4jOFYWGvjNfvBbJLNLFPeBJgZ5fTg3eFw16f9CseueUmehW42esWjCP97u_o_oNPmjH6LLamA4XQlCxATKlaI11N9c98PpsXVdpbUqkh9NMQmusQPmZUmCsqnsC4zH4CJ-cNxqJjfYcZw0pH_zZWSNVoP3K8qEsTcbyYDwEpsLoiq1NzmnEnH_YF73LVBAOG25378WnKajOzPFP4IMabTun3SaJI--FWaLUNPNz6Qil9-TDf9sjTwCYIfsC-bWDKxajGVamA93nCGSyQVjAhm-J1r-Iypw8qOd37lqy8YaQ_0I5Pg6gSc3zmL3ZX2HIfVe4l0-MTMiKu0bQ9wQu7ufyqP344mmZkvJlIfrkvtnlNUkdDHKodX7_Q\\\", \\\"processed_unicorn_ids\\\": [], \\\"is_end_of_serp\\\": false}\"}, \"result_ids_shown\": [], \"unit_id_logging_fields\": {\"num_total_modules\": 1, \"num_total_results\": 7, \"num_total_vertical_results\": 7}, \"entity_ids_shown_by_type\": {}, \"processed_unicorn_ids\": [], \"completed_flows\": [\"INTERNAL_DEBUG_MODULE\", \"SEARCH_CONTROLS_INTERCEPT\", \"INTEGRITY\", \"SPELLER\"], \"custom_cursors_serialized\": {}}", "total": null, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoie1wicGFnZV9udW1iZXJcIjogMCwgXCJmbG93X2N1cnNvcnNfc2VyaWFsaXplZFwiOiB7XCJJTlRFUk5BTF9ERUJVR19NT0RVTEVcIjogXCJ7fVwiLCBcIlNFQVJDSF9DT05UUk9MU19JTlRFUkNFUFRcIjogXCJ7fVwiLCBcIklOVEVHUklUWVwiOiBcIntcXFwiaGFzX21vcmVfcmVzdWx0c1xcXCI6ZmFsc2UsXFxcInByb2Nlc3NlZF91bmljb3JuX2lkc1xcXCI6W10sXFxcImlzX2VuZF9vZl9zZXJwXFxcIjpmYWxzZX1cIiwgXCJTUEVMTEVSXCI6IFwie31cIiwgXCJQQUdFU19UQUJcIjogXCJ7XFxcImhhc19tb3JlX3Jlc3VsdHNcXFwiOiB0cnVlLCBcXFwiYnJvd3NlX2N1cnNvcl9zZXJpYWxpemVkXFxcIjogXFxcIkFicXhBYWhtY3gzY2M0WTdLWW5sQTlhV2h2eHREaElhVk83MWpCRTNlelB2QThCVGNrU3hoYWdEdVNseUtiZWZKWFo3Y2QxTjdHazc3a3EwVmZNc3RnQXFyQ0FBdDlwMnRxTFhMRFNWZS1BMWc5aDMxNVpoaWFoaGtxQTMxVGY1ck14NDBPXzAtNTFtdWFqRGxTSEYwUHUzc3ZtaHlnSUxHOXNOM0kybDdTNEo0aDhIM1AtbDZrNGpPRllXR3ZqTmZ2QmJKTE5MRlBlQkpnWjVmVGczZUZ3MTZmOUNzZXVlVW1laFc0MmVzV2pDUDk3dV9vX29OUG1qSDZMTGFtQTRYUWxDeEFUS2xhSTExTjljOThQcHNYVmRwYlVxa2g5Tk1RbXVzUVBtWlVtQ3NxbnNDNHpINENKLWNOeHFKamZZY1p3MHBIX3paV1NOVm9QM0s4cUVzVGNieVlEd0Vwc0xvaXExTnptbkVuSF9ZRjczTFZCQU9HMjUzNzhXbkthak96UEZQNElNYWJUdW4zU2FKSS0tRldhTFVOUE56NlFpbDktVERmOXNqVHdDWUlmc0MtYldES3hhakdWYW1BOTNuQ0dTeVFWakFobS1KMXItSXlwdzhxT2QzN2xxeThZYVFfMEk1UGc2Z1NjM3ptTDNaWDJISWZWZTRsMC1NVE1pS3UwYlE5d1F1N3VmeXFQMzQ0bW1aa3ZKbElmcmt2dG5sTlVrZERIS29kWDdfUVxcXCIsIFxcXCJwcm9jZXNzZWRfdW5pY29ybl9pZHNcXFwiOiBbXSwgXFxcImlzX2VuZF9vZl9zZXJwXFxcIjogZmFsc2V9XCJ9LCBcInJlc3VsdF9pZHNfc2hvd25cIjogW10sIFwidW5pdF9pZF9sb2dnaW5nX2ZpZWxkc1wiOiB7XCJudW1fdG90YWxfbW9kdWxlc1wiOiAxLCBcIm51bV90b3RhbF9yZXN1bHRzXCI6IDcsIFwibnVtX3RvdGFsX3ZlcnRpY2FsX3Jlc3VsdHNcIjogN30sIFwiZW50aXR5X2lkc19zaG93bl9ieV90eXBlXCI6IHt9LCBcInByb2Nlc3NlZF91bmljb3JuX2lkc1wiOiBbXSwgXCJjb21wbGV0ZWRfZmxvd3NcIjogW1wiSU5URVJOQUxfREVCVUdfTU9EVUxFXCIsIFwiU0VBUkNIX0NPTlRST0xTX0lOVEVSQ0VQVFwiLCBcIklOVEVHUklUWVwiLCBcIlNQRUxMRVJcIl0sIFwiY3VzdG9tX2N1cnNvcnNfc2VyaWFsaXplZFwiOiB7fX0iLCJlIjoiZmFjZWJvb2svc2VhcmNoL3BhZ2VzIiwicCI6ImN1cnNvciJ9", "has_more": true, "page_size": 7 }, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/search/people": { "get": { "summary": "Search Facebook people by keyword", "description": "Searches public Facebook people by keyword and returns unified Author items: profile id, display name, permalink, avatar, and verified flag. The id is often a `pfbid` token rather than a numeric user id. Follower counts are not on this search card. About 7 people a page. Pass `location_uid` to scope the people tab to a city, the same way /v1/facebook/search/pages already does. Forward `pagination.next_cursor` as `cursor`.", "tags": [ "facebook" ], "operationId": "get_facebook_search_people", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Name or phrase to search for.", "schema": { "type": "string" }, "example": "NASA" }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from the previous response.", "schema": { "type": "string" } }, { "name": "location_uid", "in": "query", "required": false, "description": "Facebook location id to scope the search to a city.", "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": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 120 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 120 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/search/people" }, "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": [ "number", "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": [ "number", "null" ], "description": "Number of accounts followed" }, "posts_count": { "type": [ "number", "null" ], "description": "Total number of posts / videos / tracks / episodes" }, "likes_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at author.ext.employee_count_range.start" }, "end": { "type": [ "number", "null" ], "description": "Numeric at author.ext.employee_count_range.end" } } }, "founded_year": { "type": [ "number", "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": [ "object", "null" ], "description": "Object at author.ext.headquarters" }, "locations": { "type": [ "array", "null" ], "description": "Array at author.ext.locations", "items": { "description": "Leaf at author.ext.locations" } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at author.ext.hashtags", "items": { "description": "Leaf at author.ext.hashtags" } }, "funding": { "type": [ "object", "null" ], "description": "Object 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": [ "number", "null" ], "description": "Numeric at author.ext.rating_count" }, "talking_about_count": { "type": [ "number", "null" ], "description": "Numeric at author.ext.talking_about_count" }, "business_hours": { "type": [ "array", "null" ], "description": "Array at author.ext.business_hours", "items": { "description": "Leaf at author.ext.business_hours" } }, "links": { "type": [ "array", "null" ], "description": "Array at author.ext.links", "items": { "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" ], "enum": [ "app", "web", 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": [ "number", "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": [ "object", "null" ], "description": "Object 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": [ "object", "null" ], "description": "Object at author.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: author.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at author.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at author.ext.localizations.*.description" } } } }, "monthly_listeners": { "type": [ "number", "null" ], "description": "Numeric at author.ext.monthly_listeners" }, "total_ratings": { "type": [ "number", "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": [ "number", "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": "object", "description": "Object at author.ext.rules" } }, "weekly_active_users": { "type": [ "number", "null" ], "description": "Numeric at author.ext.weekly_active_users" }, "weekly_contributions": { "type": [ "number", "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": [ "number", "null" ], "description": "Numeric at author.ext.post_karma" }, "comment_karma": { "type": [ "number", "null" ], "description": "Numeric at author.ext.comment_karma" }, "awardee_karma": { "type": [ "number", "null" ], "description": "Numeric at author.ext.awardee_karma" }, "trophy_count": { "type": [ "number", "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": { "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": [ "object", "null" ], "description": "Object at author.ext.group" }, "search_hit": { "type": [ "object", "null" ], "description": "Nested object: author.ext.search_hit", "properties": { "match": { "type": [ "string", "null" ], "enum": [ "group_page", "post_in_group", "channel_page", "post_in_channel", 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": [ "number", "null" ], "description": "Numeric at author.ext.visitors_today" }, "visitors_total": { "type": [ "number", "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." }, "walk": { "type": "object", "description": "Present when the request sent a row-walk param (`max_pages` above 1, `max_items`, `max_credits`, a row filter, `sort_rows` or `seen`). What the walk did across the pages it fetched. Each page is billed as one call, and its charge is recorded under its own request id.", "properties": { "pages": { "type": "integer", "description": "Pages fetched.", "example": 3 }, "stopped": { "type": "string", "enum": [ "end", "max_pages", "max_items", "max_credits", "time_budget", "page_error" ], "description": "Why the walk stopped. `end`: the list ran out. `max_pages`, `max_items` or `max_credits`: the limit you set was reached. `time_budget`: the request's time budget ran low. `page_error`: a later page failed. Unless it is `end`, `pagination.next_cursor` continues from where the walk stopped.", "example": "max_pages" }, "rows_fetched": { "type": "integer", "description": "Rows read across every page, before any filter.", "example": 60 }, "rows_returned": { "type": "integer", "description": "Rows in `data.items`.", "example": 41 }, "discarded": { "type": "object", "description": "Present when you sent a row filter. Rows the filters removed, counted once each under the first filter they failed. A row a filter cannot verify (no view count, no date, no country) is discarded.", "properties": { "views_below_min": { "type": "integer", "description": "Rows with fewer views than `min_views`." }, "views_unknown": { "type": "integer", "description": "Rows with no view count, when `min_views` was sent." }, "older_than_max_age": { "type": "integer", "description": "Rows published before the `max_age_days` window." }, "date_unknown": { "type": "integer", "description": "Rows with no publish date, when `max_age_days` was sent." }, "country_not_included": { "type": "integer", "description": "Rows registered to a country that is not in `country`." }, "country_unknown": { "type": "integer", "description": "Rows with no country, when `country` was sent." }, "country_excluded": { "type": "integer", "description": "Rows registered to a country listed in `exclude_country`." } } }, "repeats": { "type": "integer", "description": "Present when you sent `seen`: rows removed because your account already received them under that id." }, "duplicates": { "type": "integer", "description": "Present when above zero: rows a later page repeated from an earlier page of the same walk, kept once." }, "credits": { "type": "object", "description": "What the pages cost.", "properties": { "pages": { "type": "integer", "description": "Credits charged for the pages walked, before refunds." }, "refunded": { "type": "integer", "description": "Credits refunded across the pages." } } }, "request_ids": { "type": "array", "description": "The request id of each page walked. Each is its own entry in `GET /v1/credits/transactions`.", "items": { "type": "string", "description": "A row id." } } } }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/search/people", "data": { "items": [ { "author": { "id": "user_43a5bc", "username": null, "display_name": "user_7fb6aa", "avatar_url": "https://example.com/avatars/user_6d11e9.png", "bio": null, "verified": false, "followers": null, "following": null, "posts_count": null, "likes_count": null, "url": "https://example.com/user_671bad", "private": null, "joined_at": null } }, { "author": { "id": "user_8d0278", "username": null, "display_name": "user_cb3dab", "avatar_url": "https://example.com/avatars/user_a6a571.png", "bio": null, "verified": false, "followers": null, "following": null, "posts_count": null, "likes_count": null, "url": "https://example.com/user_10b486", "private": null, "joined_at": null } } ], "next_cursor": "{\"page_number\": 0, \"flow_cursors_serialized\": {\"INTERNAL_DEBUG_MODULE\": \"{}\", \"SEARCH_CONTROLS_INTERCEPT\": \"{}\", \"INTEGRITY\": \"{\\\"has_more_results\\\":false,\\\"processed_unicorn_ids\\\":[],\\\"is_end_of_serp\\\":false}\", \"SPELLER\": \"{}\", \"SOCIAL_RAG\": \"{}\", \"XE_LINK_GROWTH_UPSELL_PEOPLE_TAB\": \"{}\", \"PEOPLE_TAB_UNICORN_CACHE\": \"{}\", \"PEOPLE_TAB\": \"{\\\"has_more_results\\\": true, \\\"browse_cursor_serialized\\\": \\\"AbreRI36RrSQhs-M7X2iozBXVE4gi3vX0lc58J7Ft3nSm9yU13mUOTjNPiwdOVc4YcvA-I-P0w4zonvm2JptDEfGBtYDvqYCKht7qLAdC2hybPGHhhFukROFNdOpnI8Luc2LS7Y6sToAERecD923JpWL2HlFzXjAOKastypk7PVGDsM0mVL_RllgT0tUL32h8V4vAYkIVt1jeSf_w0gltM-7tgpEDsK9MOR0_fHQZ0s70F0PR-Z8ChamjONyb42bPP0QTofLhIorqUwN_3NBXjp5Kl-RZ58iTuUGpEpWPpXCJQKP5HuyowJj3OBuU0C9BnarS4A7B-IGd3yaYwSsvBcD4FTRtxCkWXS-d237gcjTS10bWhk02zZRweXBAfw4zizeoQ-_l3vHr7sOkcKEOPLKSZJsa9P72KXkzsVxTIwQfy91jGVBhvLSWqeJ4HsI-MyaFAP7xvWSZi5dJOe7wE_k6HLfpfZG5Nwo7L6bEvB74u497gG1rhY-ACkSRvLeOLTJOOPNocHQxQ9JkCpsNG1cJ4YGxyNlbeRI3vXH13jP0g\\\", \\\"processed_unicorn_ids\\\": [], \\\"is_end_of_serp\\\": false}\"}, \"result_ids_shown\": [], \"unit_id_logging_fields\": {\"num_total_modules\": 1, \"num_total_results\": 7, \"num_total_vertical_results\": 7}, \"entity_ids_shown_by_type\": {}, \"processed_unicorn_ids\": [], \"completed_flows\": [\"INTERNAL_DEBUG_MODULE\", \"SEARCH_CONTROLS_INTERCEPT\", \"INTEGRITY\", \"SPELLER\", \"SOCIAL_RAG\", \"XE_LINK_GROWTH_UPSELL_PEOPLE_TAB\", \"PEOPLE_TAB_UNICORN_CACHE\"], \"custom_cursors_serialized\": {}}", "total": null, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoie1wicGFnZV9udW1iZXJcIjogMCwgXCJmbG93X2N1cnNvcnNfc2VyaWFsaXplZFwiOiB7XCJJTlRFUk5BTF9ERUJVR19NT0RVTEVcIjogXCJ7fVwiLCBcIlNFQVJDSF9DT05UUk9MU19JTlRFUkNFUFRcIjogXCJ7fVwiLCBcIklOVEVHUklUWVwiOiBcIntcXFwiaGFzX21vcmVfcmVzdWx0c1xcXCI6ZmFsc2UsXFxcInByb2Nlc3NlZF91bmljb3JuX2lkc1xcXCI6W10sXFxcImlzX2VuZF9vZl9zZXJwXFxcIjpmYWxzZX1cIiwgXCJTUEVMTEVSXCI6IFwie31cIiwgXCJTT0NJQUxfUkFHXCI6IFwie31cIiwgXCJYRV9MSU5LX0dST1dUSF9VUFNFTExfUEVPUExFX1RBQlwiOiBcInt9XCIsIFwiUEVPUExFX1RBQl9VTklDT1JOX0NBQ0hFXCI6IFwie31cIiwgXCJQRU9QTEVfVEFCXCI6IFwie1xcXCJoYXNfbW9yZV9yZXN1bHRzXFxcIjogdHJ1ZSwgXFxcImJyb3dzZV9jdXJzb3Jfc2VyaWFsaXplZFxcXCI6IFxcXCJBYnJlUkkzNlJyU1Focy1NN1gyaW96QlhWRTRnaTN2WDBsYzU4SjdGdDNuU205eVUxM21VT1RqTlBpd2RPVmM0WWN2QS1JLVAwdzR6b252bTJKcHRERWZHQnRZRHZxWUNLaHQ3cUxBZEMyaHliUEdIaGhGdWtST0ZOZE9wbkk4THVjMkxTN1k2c1RvQUVSZWNEOTIzSnBXTDJIbEZ6WGpBT0thc3R5cGs3UFZHRHNNMG1WTF9SbGxnVDB0VUwzMmg4VjR2QVlrSVZ0MWplU2ZfdzBnbHRNLTd0Z3BFRHNLOU1PUjBfZkhRWjBzNzBGMFBSLVo4Q2hhbWpPTnliNDJiUFAwUVRvZkxoSW9ycVV3Tl8zTkJYanA1S2wtUlo1OGlUdVVHcEVwV1BwWENKUUtQNUh1eW93SmozT0J1VTBDOUJuYXJTNEE3Qi1JR2QzeWFZd1NzdkJjRDRGVFJ0eENrV1hTLWQyMzdnY2pUUzEwYldoazAyelpSd2VYQkFmdzR6aXplb1EtX2wzdkhyN3NPa2NLRU9QTEtTWkpzYTlQNzJLWGt6c1Z4VEl3UWZ5OTFqR1ZCaHZMU1dxZUo0SHNJLU15YUZBUDd4dldTWmk1ZEpPZTd3RV9rNkhMZnBmWkc1TndvN0w2YkV2Qjc0dTQ5N2dHMXJoWS1BQ2tTUnZMZU9MVEpPT1BOb2NIUXhROUprQ3BzTkcxY0o0WUd4eU5sYmVSSTN2WEgxM2pQMGdcXFwiLCBcXFwicHJvY2Vzc2VkX3VuaWNvcm5faWRzXFxcIjogW10sIFxcXCJpc19lbmRfb2Zfc2VycFxcXCI6IGZhbHNlfVwifSwgXCJyZXN1bHRfaWRzX3Nob3duXCI6IFtdLCBcInVuaXRfaWRfbG9nZ2luZ19maWVsZHNcIjoge1wibnVtX3RvdGFsX21vZHVsZXNcIjogMSwgXCJudW1fdG90YWxfcmVzdWx0c1wiOiA3LCBcIm51bV90b3RhbF92ZXJ0aWNhbF9yZXN1bHRzXCI6IDd9LCBcImVudGl0eV9pZHNfc2hvd25fYnlfdHlwZVwiOiB7fSwgXCJwcm9jZXNzZWRfdW5pY29ybl9pZHNcIjogW10sIFwiY29tcGxldGVkX2Zsb3dzXCI6IFtcIklOVEVSTkFMX0RFQlVHX01PRFVMRVwiLCBcIlNFQVJDSF9DT05UUk9MU19JTlRFUkNFUFRcIiwgXCJJTlRFR1JJVFlcIiwgXCJTUEVMTEVSXCIsIFwiU09DSUFMX1JBR1wiLCBcIlhFX0xJTktfR1JPV1RIX1VQU0VMTF9QRU9QTEVfVEFCXCIsIFwiUEVPUExFX1RBQl9VTklDT1JOX0NBQ0hFXCJdLCBcImN1c3RvbV9jdXJzb3JzX3NlcmlhbGl6ZWRcIjoge319IiwiZSI6ImZhY2Vib29rL3NlYXJjaC9wZW9wbGUiLCJwIjoiY3Vyc29yIn0", "has_more": true, "page_size": 7 }, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/search/videos": { "get": { "summary": "Search Facebook videos by keyword", "description": "Searches public Facebook videos and reels by keyword and returns unified Post items: video id, caption, permalink, thumbnail, the author's name and numeric id (`post.ext.author_id`), the author's profile URL (`post.ext.author_url`), and the verified flag where Facebook shows it. Facebook's search card carries no counts, no duration and no publish date (its view count is a rounded display string that runs well below the real count, so it is never parsed), so on a plain call `post.engagement`, `post.content.duration_seconds`, `post.published_at` and `post.author.avatar_url` are null on every row. Send `include=details` and every video is joined, in the same call, to the per-post lookup for its permalink: the exact view, like, comment and share counts (`post.engagement.views`, `.likes`, `.comments` and `.shares`), the duration, the publish time, the author's avatar and the per-reaction breakdown (`post.ext.reaction_counts`) land on each row. The video id, permalink, caption and thumbnail the search row carries are never replaced. With `start_date` or `end_date`, the join dates every video and a video dated outside your window is then dropped; its lookup is still billed, since the search card carries no date to filter on before it. Cost: 1 credit for the page plus 1 credit per video filled from a fresh lookup (7 videos a page, so 8 credits at most); rows already in cache are filled for free, rows that could not be filled are refunded, and a repeat of the same call within the cache window is 0 credits. Time: `include=details` adds 3 to 5 seconds on a fresh page (the lookups run in parallel and the call waits for the slowest, never more than 12 seconds) and nothing when the rows are already cached. The response carries a `hydration` block itemising rows, lookups, cache hits, credits and milliseconds. About 7 videos a page. Forward `pagination.next_cursor` as `cursor`.", "tags": [ "facebook" ], "operationId": "get_facebook_search_videos", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 8, "x-credit-cost-formula": "1 credit for the page. include=details holds 1 credit per video (7 a page) and keeps only the rows filled from a fresh lookup, so a page is at most 8 credits; rows served from cache are free, unfilled rows 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": "query", "in": "query", "required": true, "description": "Keyword or phrase to search for.", "schema": { "type": "string" }, "example": "NASA" }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from the previous response.", "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "required": false, "description": "Include videos on or after this date (YYYY-MM-DD).", "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "description": "Include videos on or before this date (YYYY-MM-DD).", "schema": { "type": "string" } }, { "name": "recent_videos", "in": "query", "required": false, "description": "When true, rank by recency instead of relevance.", "schema": { "type": "boolean" } }, { "name": "location_uid", "in": "query", "required": false, "description": "Facebook location id to scope the search.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Set to `details` (one token only) to fill `post.engagement.views`, `.likes`, `.comments` and `.shares`, `post.content.duration_seconds`, `post.published_at`, `post.author.avatar_url` and `post.ext.reaction_counts` on every video in this one call. Holds 1 credit per video (7 a page) and keeps only the rows filled from a fresh lookup: rows already in cache and rows the lookup cannot fill are refunded, so a page is never more than 8 credits. The join takes 3 to 5 seconds on a fresh page, never more than 12, and nothing when the rows are already cached; read `data.hydration` for the rows, the credits held and kept, and the time. Without it the call is unchanged.", "schema": { "type": "string", "enum": [ "details" ] } }, { "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": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 120 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 120 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/search/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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "number", "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": [ "number", "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": [ "number", "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", "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "number", "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; discover reads a country from it into `geo.country` (`source: author_location`). 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": [ "number", "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" }, "link_domain": { "type": [ "string", "null" ], "description": "String at post.ext.link_domain" }, "upvote_ratio": { "type": [ "number", "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" ], "enum": [ "video", "short", "live", "channel", "playlist", 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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "enum": [ "image", "video", "carousel", 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": [ "number", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "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": { "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": { "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": [ "object", "null" ], "description": "Object 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": { "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/profile/posts`, `/v1/instagram/profile/reels`, `/v1/instagram/search/reels`, `/v1/tiktok/profile/videos` 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": [ "object", "null" ], "description": "Object 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", "enum": [ "image", "video" ], "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "number", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "number", "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": [ "number", "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": [ "object", "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": [ "object", "null" ], "description": "Object at post.ext.retweeted_post" }, "quote_count": { "type": [ "number", "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": { "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": [ "object", "null" ], "description": "Object 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": "object", "description": "Object 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": [ "number", "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": [ "object", "null" ], "description": "Object at post.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: post.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.description" } } } }, "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" ], "enum": [ "minute", "hour", "day", "week", "month", "year", 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": [ "number", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "number", "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": [ "object", "null" ], "description": "Object 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": [ "number", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "object", "null" ], "description": "Object at post.ext.dsp_ids", "additionalProperties": { "type": "string", "description": "String 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": "object", "description": "Object at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "object", "description": "Object at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "object", "description": "Object 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": [ "object", "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": [ "object", "null" ], "description": "Object 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": [ "number", "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": "number", "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": [ "object", "null" ], "description": "Object at post.ext.event" }, "trend": { "type": [ "object", "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" }, "numeric_id": { "type": [ "number", "null" ], "description": "Numeric at post.ext.numeric_id" }, "outbound_url": { "type": [ "string", "null" ], "description": "String at post.ext.outbound_url" }, "group": { "type": [ "object", "null" ], "description": "Object at post.ext.group" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "number", "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": [ "number", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "number", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "number", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "enum": [ "target", "other_named_thing", "generic_word", "not_present" ], "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "number", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "number", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "string", "boolean", "null" ], "description": "Union: number | string | boolean" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } } } } } } }, "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." }, "walk": { "type": "object", "description": "Present when the request sent a row-walk param (`max_pages` above 1, `max_items`, `max_credits`, a row filter, `sort_rows` or `seen`). What the walk did across the pages it fetched. Each page is billed as one call, and its charge is recorded under its own request id.", "properties": { "pages": { "type": "integer", "description": "Pages fetched.", "example": 3 }, "stopped": { "type": "string", "enum": [ "end", "max_pages", "max_items", "max_credits", "time_budget", "page_error" ], "description": "Why the walk stopped. `end`: the list ran out. `max_pages`, `max_items` or `max_credits`: the limit you set was reached. `time_budget`: the request's time budget ran low. `page_error`: a later page failed. Unless it is `end`, `pagination.next_cursor` continues from where the walk stopped.", "example": "max_pages" }, "rows_fetched": { "type": "integer", "description": "Rows read across every page, before any filter.", "example": 60 }, "rows_returned": { "type": "integer", "description": "Rows in `data.items`.", "example": 41 }, "discarded": { "type": "object", "description": "Present when you sent a row filter. Rows the filters removed, counted once each under the first filter they failed. A row a filter cannot verify (no view count, no date, no country) is discarded.", "properties": { "views_below_min": { "type": "integer", "description": "Rows with fewer views than `min_views`." }, "views_unknown": { "type": "integer", "description": "Rows with no view count, when `min_views` was sent." }, "older_than_max_age": { "type": "integer", "description": "Rows published before the `max_age_days` window." }, "date_unknown": { "type": "integer", "description": "Rows with no publish date, when `max_age_days` was sent." }, "country_not_included": { "type": "integer", "description": "Rows registered to a country that is not in `country`." }, "country_unknown": { "type": "integer", "description": "Rows with no country, when `country` was sent." }, "country_excluded": { "type": "integer", "description": "Rows registered to a country listed in `exclude_country`." } } }, "repeats": { "type": "integer", "description": "Present when you sent `seen`: rows removed because your account already received them under that id." }, "duplicates": { "type": "integer", "description": "Present when above zero: rows a later page repeated from an earlier page of the same walk, kept once." }, "credits": { "type": "object", "description": "What the pages cost.", "properties": { "pages": { "type": "integer", "description": "Credits charged for the pages walked, before refunds." }, "refunded": { "type": "integer", "description": "Credits refunded across the pages." } } }, "request_ids": { "type": "array", "description": "The request id of each page walked. Each is its own entry in `GET /v1/credits/transactions`.", "items": { "type": "string", "description": "A row id." } } } }, "hydration": { "type": "object", "description": "Present when the request asked for a row join with `include=`, or sent a param that implies one. What the join did and what it cost. On a multi-page walk it sums every page. A join that always runs for free is left out.", "properties": { "include": { "type": "string", "description": "The token that switched the join on.", "example": "profile" }, "implied_by": { "type": "string", "description": "Present when you did not send `include` and another param switched the join on. The join's credits (`extra_credits`) are then part of `credits_used`. Absent when you sent `include` yourself." }, "rows": { "type": "integer", "description": "Rows on the page after any row cap.", "example": 20 }, "looked_up": { "type": "integer", "description": "Rows that needed a lookup (at least one field the join fills was empty).", "example": 20 }, "filled": { "type": "integer", "description": "Rows where at least one field was filled by the join.", "example": 18 }, "cached": { "type": "integer", "description": "Of `filled`, rows filled from the sibling endpoint's cache at no charge.", "example": 0 }, "unfilled": { "type": "integer", "description": "Rows that needed a lookup and were not filled (the lookup failed, was skipped, or had nothing to copy). Their credits are refunded.", "example": 2 }, "credits_held": { "type": "integer", "description": "Credits held up front for the join, on top of the page's own price.", "example": 20 }, "extra_credits": { "type": "integer", "description": "Of `credits_held`, the credits kept: one lookup's price for each distinct key filled from a fresh lookup. The rest was refunded.", "example": 18 }, "ms": { "type": "integer", "description": "Time the join added, in milliseconds.", "example": 2400 }, "cached_page": { "type": "boolean", "description": "True when the whole page was served from cache, so the join cost nothing on this call.", "example": true }, "batches": { "type": "integer", "description": "Joins that look rows up in batches only: how many batch calls were made. Absent on a join that looks rows up one by one." }, "from_earlier_pages": { "type": "integer", "description": "`max_pages`, `max_items` and `max_credits` walks only: rows filled free from a key already looked up on an earlier page of the same walk. Not counted in `looked_up`, `filled` or `cached`. Absent when zero." }, "steps": { "type": "array", "description": "Present when the request asked for more than one join (`include=engagement,channel`): one report per join, in the order they ran. The top-level numbers are then the page's: rows looked up or filled by any join, and the credits and time of all of them together.", "items": { "type": "object", "description": "One join's report.", "properties": { "include": { "type": "string", "description": "The token that switched the join on.", "example": "profile" }, "implied_by": { "type": "string", "description": "Present when you did not send `include` and another param switched the join on. The join's credits (`extra_credits`) are then part of `credits_used`. Absent when you sent `include` yourself." }, "rows": { "type": "integer", "description": "Rows on the page after any row cap.", "example": 20 }, "looked_up": { "type": "integer", "description": "Rows that needed a lookup (at least one field the join fills was empty).", "example": 20 }, "filled": { "type": "integer", "description": "Rows where at least one field was filled by the join.", "example": 18 }, "cached": { "type": "integer", "description": "Of `filled`, rows filled from the sibling endpoint's cache at no charge.", "example": 0 }, "unfilled": { "type": "integer", "description": "Rows that needed a lookup and were not filled (the lookup failed, was skipped, or had nothing to copy). Their credits are refunded.", "example": 2 }, "credits_held": { "type": "integer", "description": "Credits held up front for the join, on top of the page's own price.", "example": 20 }, "extra_credits": { "type": "integer", "description": "Of `credits_held`, the credits kept: one lookup's price for each distinct key filled from a fresh lookup. The rest was refunded.", "example": 18 }, "ms": { "type": "integer", "description": "Time the join added, in milliseconds.", "example": 2400 }, "cached_page": { "type": "boolean", "description": "True when the whole page was served from cache, so the join cost nothing on this call.", "example": true }, "batches": { "type": "integer", "description": "Joins that look rows up in batches only: how many batch calls were made. Absent on a join that looks rows up one by one." }, "from_earlier_pages": { "type": "integer", "description": "`max_pages`, `max_items` and `max_credits` walks only: rows filled free from a key already looked up on an earlier page of the same walk. Not counted in `looked_up`, `filled` or `cached`. Absent when zero." } } } } } }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/search/videos", "data": { "items": [ { "post": { "id": "930452829785006", "url": "https://www.facebook.com/reel/930452829785006/", "content": { "text": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "media_urls": "https://scontent.fcai20-6.fna.fbcdn.net/v/t15.5256-10/831523658_1611774573927132_8621044786914934392_n.jpg?stp=c0.0.400.224a_dst-jpg_p75x225_tt6&_nc_cat=101&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e3495b&_nc_ohc=hqD6g5aaICIQ7kNvwGoq_Na&_nc_oc=AdqenUMGHLGr95fdRkERvtFfdKKA5fwWQQD6FQQSBUmd9Y_VPE8UqWjeRrz3TzP7Dr0&_nc_zt=23&_nc_ht=scontent.fcai20-6.fna&_nc_gid=8dTYUQ7lohMLsZ1wUCGBtA&_nc_ss=70289&oh=00_AQO08HTeDMoqJE3RudkPgBD_1fkktPfnVbJdp9G9y_UJXA&oe=6AC5671E", "thumbnail_url": "https://scontent.fcai20-6.fna.fbcdn.net/v/t15.5256-10/831523658_1611774573927132_8621044786914934392_n.jpg?stp=c0.0.400.224a_dst-jpg_p75x225_tt6&_nc_cat=101&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e3495b&_nc_ohc=hqD6g5aaICIQ7kNvwGoq_Na&_nc_oc=AdqenUMGHLGr95fdRkERvtFfdKKA5fwWQQD6FQQSBUmd9Y_VPE8UqWjeRrz3TzP7Dr0&_nc_zt=23&_nc_ht=scontent.fcai20-6.fna&_nc_gid=8dTYUQ7lohMLsZ1wUCGBtA&_nc_ss=70289&oh=00_AQO08HTeDMoqJE3RudkPgBD_1fkktPfnVbJdp9G9y_UJXA&oe=6AC5671E", "duration_seconds": null }, "author": { "username": null, "display_name": "user_4da615", "avatar_url": null, "verified": null }, "engagement": { "views": null, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": null, "ext": { "author_id": "user_9e601d" } }, "computed": { "engagement_rate": null, "language": "en", "content_category": "other", "estimated_reach": null } }, { "post": { "id": "1408202287429345", "url": "https://www.facebook.com/user_06552e/videos/1408202287429345/", "content": { "text": null, "media_urls": "https://scontent.fcai20-6.fna.fbcdn.net/v/t15.5256-10/833702270_1116273988013078_2590966426497346164_n.jpg?stp=c0.0.400.224a_dst-jpg_p75x225_tt6&_nc_cat=102&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e3495b&_nc_ohc=otKs_lDeTRMQ7kNvwGx86Y6&_nc_oc=AdoCBNb8oV_Bi9LI19OyzkWdGcDuSmSNlI9FFKUszR6QmFfqUfynzUXb3m3ACBS70ZY&_nc_zt=23&_nc_ht=scontent.fcai20-6.fna&_nc_gid=8dTYUQ7lohMLsZ1wUCGBtA&_nc_ss=70289&oh=00_AQPBjraQ60mbWU_I8LZ8qQQbwokF26TPDoXOrpFVYart-g&oe=6AC5629B", "thumbnail_url": "https://scontent.fcai20-6.fna.fbcdn.net/v/t15.5256-10/833702270_1116273988013078_2590966426497346164_n.jpg?stp=c0.0.400.224a_dst-jpg_p75x225_tt6&_nc_cat=102&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e3495b&_nc_ohc=otKs_lDeTRMQ7kNvwGx86Y6&_nc_oc=AdoCBNb8oV_Bi9LI19OyzkWdGcDuSmSNlI9FFKUszR6QmFfqUfynzUXb3m3ACBS70ZY&_nc_zt=23&_nc_ht=scontent.fcai20-6.fna&_nc_gid=8dTYUQ7lohMLsZ1wUCGBtA&_nc_ss=70289&oh=00_AQPBjraQ60mbWU_I8LZ8qQQbwokF26TPDoXOrpFVYart-g&oe=6AC5629B", "duration_seconds": null }, "author": { "username": null, "display_name": "user_4da615", "avatar_url": null, "verified": null }, "engagement": { "views": null, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": null, "ext": { "author_id": "user_9e601d" } }, "computed": { "engagement_rate": null, "language": null, "content_category": null, "estimated_reach": null } } ], "next_cursor": "{\"page_number\": 0, \"flow_cursors_serialized\": {\"INTERNAL_DEBUG_MODULE\": \"{}\", \"SEARCH_CONTROLS_INTERCEPT\": \"{}\", \"INTEGRITY\": \"{\\\"has_more_results\\\":false,\\\"processed_unicorn_ids\\\":[],\\\"is_end_of_serp\\\":false}\", \"META_AI\": \"{\\\"has_more_results\\\":false,\\\"processed_unicorn_ids\\\":[],\\\"is_end_of_serp\\\":false}\", \"SPELLER\": \"{}\", \"VIDEOS_CACHED_CONTENT\": \"{}\", \"ADHOC_RESULTS_INJECTION\": \"{}\", \"SEARCH_ADS_TOP_POSITION\": \"{}\", \"VIDEOS_TAB\": \"{\\\"has_more_results\\\": true, \\\"browse_cursor_serialized\\\": \\\"AbpWwnv_GO5N-zIx8zv9Wk0KLPtJ-vvssInzWTfefMpBCClDy8Gj1qrNnjuxa2Tb7Idttk_PfTy32HcpRQE7B_aJ5UyfqzeOMwM2Z0A8-LWVVwGsmeaN47ha2MTwPbNwb14IhMBCB38F_wXCR6CV9eTN2QYCkvDi68ieeIlAl7PRV4zOEufg816mGyj8Euhm-c7gXIV0-rkc3w2ksyiVPmhxmUnhTOnhORcy1AjMa9_qfnmgI7AsnJ1xm03JVPU5Mcav8vS9HtECa1B_RpcbYclPbRZiDUirgJ2WPM8H7YTa7TWK-_kkaYy7Kn5LNKT95RCuZkV3PFTi3u90P-fFzybeAtD-bC1R3AaLFQoCfZI9vf5OiTIUAzN_EJTuHd4ukwH2cv5H2_IkIWZQ2jW-XzUWaKYi_AFJqMulZ0mSsP_M0_wIORvflMc-NnD4XcsaJ86NCEVvrdu-fZktBl0UYVAEUhh79_2a4DlwROKfzaywaeWKwBaSChbEATZOW_TA1fsgaacdh_TNsLYpB2pG7MybIoQQh8wvqWX6SdmPdQNmDQ\\\", \\\"processed_unicorn_ids\\\": [], \\\"is_end_of_serp\\\": false}\", \"PARALLEL_FETCH_NOOP\": \"{}\"}, \"result_ids_shown\": [], \"unit_id_logging_fields\": {\"num_total_modules\": 7, \"num_total_results\": 7, \"num_total_vertical_results\": 7}, \"entity_ids_shown_by_type\": {\"browse_type_search_query\": []}, \"processed_unicorn_ids\": [], \"completed_flows\": [\"INTERNAL_DEBUG_MODULE\", \"SEARCH_CONTROLS_INTERCEPT\", \"INTEGRITY\", \"META_AI\", \"SPELLER\", \"VIDEOS_CACHED_CONTENT\", \"ADHOC_RESULTS_INJECTION\", \"SEARCH_ADS_TOP_POSITION\"], \"custom_cursors_serialized\": {}}", "total": null, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoie1wicGFnZV9udW1iZXJcIjogMCwgXCJmbG93X2N1cnNvcnNfc2VyaWFsaXplZFwiOiB7XCJJTlRFUk5BTF9ERUJVR19NT0RVTEVcIjogXCJ7fVwiLCBcIlNFQVJDSF9DT05UUk9MU19JTlRFUkNFUFRcIjogXCJ7fVwiLCBcIklOVEVHUklUWVwiOiBcIntcXFwiaGFzX21vcmVfcmVzdWx0c1xcXCI6ZmFsc2UsXFxcInByb2Nlc3NlZF91bmljb3JuX2lkc1xcXCI6W10sXFxcImlzX2VuZF9vZl9zZXJwXFxcIjpmYWxzZX1cIiwgXCJNRVRBX0FJXCI6IFwie1xcXCJoYXNfbW9yZV9yZXN1bHRzXFxcIjpmYWxzZSxcXFwicHJvY2Vzc2VkX3VuaWNvcm5faWRzXFxcIjpbXSxcXFwiaXNfZW5kX29mX3NlcnBcXFwiOmZhbHNlfVwiLCBcIlNQRUxMRVJcIjogXCJ7fVwiLCBcIlZJREVPU19DQUNIRURfQ09OVEVOVFwiOiBcInt9XCIsIFwiQURIT0NfUkVTVUxUU19JTkpFQ1RJT05cIjogXCJ7fVwiLCBcIlNFQVJDSF9BRFNfVE9QX1BPU0lUSU9OXCI6IFwie31cIiwgXCJWSURFT1NfVEFCXCI6IFwie1xcXCJoYXNfbW9yZV9yZXN1bHRzXFxcIjogdHJ1ZSwgXFxcImJyb3dzZV9jdXJzb3Jfc2VyaWFsaXplZFxcXCI6IFxcXCJBYnBXd252X0dPNU4tekl4OHp2OVdrMEtMUHRKLXZ2c3NJbnpXVGZlZk1wQkNDbER5OEdqMXFyTm5qdXhhMlRiN0lkdHRrX1BmVHkzMkhjcFJRRTdCX2FKNVV5ZnF6ZU9Nd00yWjBBOC1MV1ZWd0dzbWVhTjQ3aGEyTVR3UGJOd2IxNEloTUJDQjM4Rl93WENSNkNWOWVUTjJRWUNrdkRpNjhpZWVJbEFsN1BSVjR6T0V1Zmc4MTZtR3lqOEV1aG0tYzdnWElWMC1ya2MzdzJrc3lpVlBtaHhtVW5oVE9uaE9SY3kxQWpNYTlfcWZubWdJN0FzbkoxeG0wM0pWUFU1TWNhdjh2UzlIdEVDYTFCX1JwY2JZY2xQYlJaaURVaXJnSjJXUE04SDdZVGE3VFdLLV9ra2FZeTdLbjVMTktUOTVSQ3Vaa1YzUEZUaTN1OTBQLWZGenliZUF0RC1iQzFSM0FhTEZRb0NmWkk5dmY1T2lUSVVBek5fRUpUdUhkNHVrd0gyY3Y1SDJfSWtJV1pRMmpXLVh6VVdhS1lpX0FGSnFNdWxaMG1Tc1BfTTBfd0lPUnZmbE1jLU5uRDRYY3NhSjg2TkNFVnZyZHUtZlprdEJsMFVZVkFFVWhoNzlfMmE0RGx3Uk9LZnpheXdhZVdLd0JhU0NoYkVBVFpPV19UQTFmc2dhYWNkaF9UTnNMWXBCMnBHN015YklvUVFoOHd2cVdYNlNkbVBkUU5tRFFcXFwiLCBcXFwicHJvY2Vzc2VkX3VuaWNvcm5faWRzXFxcIjogW10sIFxcXCJpc19lbmRfb2Zfc2VycFxcXCI6IGZhbHNlfVwiLCBcIlBBUkFMTEVMX0ZFVENIX05PT1BcIjogXCJ7fVwifSwgXCJyZXN1bHRfaWRzX3Nob3duXCI6IFtdLCBcInVuaXRfaWRfbG9nZ2luZ19maWVsZHNcIjoge1wibnVtX3RvdGFsX21vZHVsZXNcIjogNywgXCJudW1fdG90YWxfcmVzdWx0c1wiOiA3LCBcIm51bV90b3RhbF92ZXJ0aWNhbF9yZXN1bHRzXCI6IDd9LCBcImVudGl0eV9pZHNfc2hvd25fYnlfdHlwZVwiOiB7XCJicm93c2VfdHlwZV9zZWFyY2hfcXVlcnlcIjogW119LCBcInByb2Nlc3NlZF91bmljb3JuX2lkc1wiOiBbXSwgXCJjb21wbGV0ZWRfZmxvd3NcIjogW1wiSU5URVJOQUxfREVCVUdfTU9EVUxFXCIsIFwiU0VBUkNIX0NPTlRST0xTX0lOVEVSQ0VQVFwiLCBcIklOVEVHUklUWVwiLCBcIk1FVEFfQUlcIiwgXCJTUEVMTEVSXCIsIFwiVklERU9TX0NBQ0hFRF9DT05URU5UXCIsIFwiQURIT0NfUkVTVUxUU19JTkpFQ1RJT05cIiwgXCJTRUFSQ0hfQURTX1RPUF9QT1NJVElPTlwiXSwgXCJjdXN0b21fY3Vyc29yc19zZXJpYWxpemVkXCI6IHt9fSIsImUiOiJmYWNlYm9vay9zZWFyY2gvdmlkZW9zIiwicCI6ImN1cnNvciJ9", "has_more": true, "page_size": 7 }, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/search/groups": { "get": { "summary": "Search Facebook groups by keyword", "description": "Finds public Facebook groups by keyword, so you can pick the groups to read before calling `/v1/facebook/group/posts`. Returns one row per group, in the order the search found them, on the same Author shape `/v1/facebook/group` returns: `author.id` is the group's key (its numeric id, or the vanity name of a group that set one), `author.url` is the canonical `https://www.facebook.com/groups//` form that `/v1/facebook/group/posts` and `/v1/facebook/group` take as `url` with no re-mapping, and `author.display_name` is the group's name. Groups are discovered through a public web search index limited to Facebook group pages, so a group is found either through its own page or through a post inside it: `author.ext.search_hit.match` says which (`group_page` or `post_in_group`), and `author.ext.search_hit` also carries the hit's `title`, `snippet` and `evidence_url` (the exact page that matched). A group found only through a post has `display_name: null`, because a post's title is not the group's name. The search hit carries no member count, description, privacy or creation date, so on a plain call `author.followers`, `author.bio`, `author.joined_at` and `author.ext.group` are null. Send `include=details` and every group is joined, in the same call, to the group lookup: the member count, the description, the creation date, the privacy and visibility labels, the posting activity (`author.ext.group.activity`), the numeric id (`author.ext.group.id`) and, where it was null, the name land on each row. Cost: 1 credit for the page plus 1 credit per group whose member count, description or activity was filled from a fresh lookup (at most 10 groups a page, so 11 credits at most); groups already in cache are free, groups that could not be filled are refunded, and a repeat of the same call within the cache window is 0 credits. Time: a plain page takes about 2 to 5 seconds; `include=details` adds 3 to 7 seconds on a fresh page (the lookups run in parallel and the call waits for the slowest, never more than 12 seconds) and nothing when the groups are already cached. The response carries a `hydration` block itemising rows, lookups, cache hits, credits and milliseconds. Every row also carries `computed.relevance` against your query, free, and `relevance=filter` drops the groups that are not about it. A page holds up to 10 groups, fewer when several hits belong to one group. Forward `pagination.next_cursor` as `cursor` for the next page. The same group can appear again on a later page, and once under its vanity name and once under its numeric id, so dedupe on `author.ext.group.id` after `include=details` when that matters. A group can be public in the search and still private to read: check `author.ext.group.privacy_label` before calling `group/posts`.", "tags": [ "facebook" ], "operationId": "get_facebook_search_groups", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-credit-cost-min": 1, "x-credit-cost-max": 15, "x-credit-cost-formula": "1 credit for the page. include=details holds 1 credit per group (at most 10 a page) and keeps only the groups filled from a fresh lookup, so a page is at most 11 credits; groups served from cache are free, unfilled groups 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. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total.", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Keywords describing the groups to find, for example `vintage cars`. Keywords only: the search is already limited to public Facebook groups, so a `site:` operator is refused before billing.", "schema": { "type": "string" }, "example": "vintage cars" }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1. Forwarding `pagination.next_cursor` as `cursor` does the same. Native upstream cursor param. Send the universal `cursor` instead: the API maps it to this name for you.", "deprecated": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "include", "in": "query", "required": false, "description": "Set to `details` (one token only) to fill, on every group in this one call, `author.followers` (members), `author.bio` (the description), `author.joined_at`, `author.ext.group.privacy_label`, `visibility_label`, `activity` and `id` (the numeric group id), and the name where it was null. Holds 1 credit per group (at most 10 a page) and keeps only the groups whose member count, description or activity was filled from a fresh lookup; groups already in cache and groups the lookup cannot fill are refunded, so a page is never more than 11 credits. The join takes 3 to 7 seconds on a fresh page, never more than 12, and nothing when the groups are already cached; read `data.hydration` for the rows, the credits held and kept, and the time. Without it the call is unchanged.", "schema": { "type": "string", "enum": [ "details" ] } }, { "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": "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 `page` (page style). You never construct, decode, or look up a cursor. Omit it for page 1.", "schema": { "type": "string" } }, { "name": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 120 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 120 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/search/groups" }, "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": [ "number", "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": [ "number", "null" ], "description": "Number of accounts followed" }, "posts_count": { "type": [ "number", "null" ], "description": "Total number of posts / videos / tracks / episodes" }, "likes_count": { "type": [ "number", "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": [ "number", "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": [ "number", "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": [ "number", "null" ], "description": "Numeric at author.ext.employee_count_range.start" }, "end": { "type": [ "number", "null" ], "description": "Numeric at author.ext.employee_count_range.end" } } }, "founded_year": { "type": [ "number", "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": [ "object", "null" ], "description": "Object at author.ext.headquarters" }, "locations": { "type": [ "array", "null" ], "description": "Array at author.ext.locations", "items": { "description": "Leaf at author.ext.locations" } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at author.ext.hashtags", "items": { "description": "Leaf at author.ext.hashtags" } }, "funding": { "type": [ "object", "null" ], "description": "Object 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": [ "number", "null" ], "description": "Numeric at author.ext.rating_count" }, "talking_about_count": { "type": [ "number", "null" ], "description": "Numeric at author.ext.talking_about_count" }, "business_hours": { "type": [ "array", "null" ], "description": "Array at author.ext.business_hours", "items": { "description": "Leaf at author.ext.business_hours" } }, "links": { "type": [ "array", "null" ], "description": "Array at author.ext.links", "items": { "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" ], "enum": [ "app", "web", 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": [ "number", "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": [ "object", "null" ], "description": "Object 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": [ "object", "null" ], "description": "Object at author.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: author.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at author.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at author.ext.localizations.*.description" } } } }, "monthly_listeners": { "type": [ "number", "null" ], "description": "Numeric at author.ext.monthly_listeners" }, "total_ratings": { "type": [ "number", "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": [ "number", "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": "object", "description": "Object at author.ext.rules" } }, "weekly_active_users": { "type": [ "number", "null" ], "description": "Numeric at author.ext.weekly_active_users" }, "weekly_contributions": { "type": [ "number", "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": [ "number", "null" ], "description": "Numeric at author.ext.post_karma" }, "comment_karma": { "type": [ "number", "null" ], "description": "Numeric at author.ext.comment_karma" }, "awardee_karma": { "type": [ "number", "null" ], "description": "Numeric at author.ext.awardee_karma" }, "trophy_count": { "type": [ "number", "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": { "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": [ "object", "null" ], "description": "Object at author.ext.group" }, "search_hit": { "type": [ "object", "null" ], "description": "Nested object: author.ext.search_hit", "properties": { "match": { "type": [ "string", "null" ], "enum": [ "group_page", "post_in_group", "channel_page", "post_in_channel", 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": [ "number", "null" ], "description": "Numeric at author.ext.visitors_today" }, "visitors_total": { "type": [ "number", "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." }, "relevance": { "type": "object", "description": "Present on a list that scores its rows against your query: free by default, or when you send `relevance=score` or `relevance=filter`. Absent with `judgments=off`. Reports what was scored, what a `filter` dropped and what it cost.", "properties": { "mode": { "type": "string", "enum": [ "score", "filter" ], "description": "`score`: rows carry `computed.relevance` and none is dropped. `filter`: rows judged off topic are also dropped.", "example": "score" }, "topic_source": { "type": "string", "enum": [ "query", "relevant_to" ], "description": "Where the topic came from: your search query, or the `relevant_to` you sent.", "example": "query" }, "origin": { "type": "string", "enum": [ "default", "requested" ], "description": "`default` when you sent no `relevance=` (score only, free, never drops or reorders), `requested` when you asked.", "example": "default" }, "rows": { "type": "integer", "description": "Rows on the page before any drop.", "example": 30 }, "scored": { "type": "integer", "description": "Rows that carry a relevance value, freshly judged or from the shared store.", "example": 30 }, "cached": { "type": "integer", "description": "Of `scored`, rows served from the shared store.", "example": 0 }, "kept": { "type": "integer", "description": "Rows left on the page.", "example": 30 }, "dropped": { "type": "integer", "description": "Rows removed by `relevance=filter`.", "example": 0 }, "dropped_ids": { "type": "array", "description": "Ids of the rows counted in `dropped`.", "items": { "type": "string", "description": "A row id." } }, "unjudged": { "type": "integer", "description": "Rows the judgment could not answer for this time. They are kept and carry `relevance: null`.", "example": 0 }, "too_short": { "type": "integer", "description": "Rows with too little text to judge. They are kept.", "example": 0 }, "threshold": { "type": "number", "description": "The probability a row needs to be kept by `relevance=filter`: 0.5, or the `relevance_threshold` you sent.", "example": 0.5 }, "extra_credits": { "type": "integer", "description": "Credits the judgment added to this call. 0 with your query as the topic.", "example": 0 }, "methodology_version": { "type": "string", "description": "The version of the relevance questions.", "example": "relevance/2" }, "status": { "type": "string", "enum": [ "complete", "partial", "skipped" ], "description": "`complete`: every row was scored. `partial`: some rows carry `relevance: null`. `skipped`: default scoring was switched off by a capacity guard.", "example": "complete" }, "pending": { "type": "integer", "description": "Rows still being judged when the page was sent.", "example": 0 }, "pending_ids": { "type": "array", "description": "Ids of the rows counted in `pending`.", "items": { "type": "string", "description": "A row id." } }, "cached_page": { "type": "boolean", "description": "Present and true when the whole page came from the response cache, so nothing was judged or charged." }, "unjudged_dropped": { "type": "object", "description": "Present on a merged multi-platform search under `relevance=filter`: rows dropped because they could not be judged in time, counted per platform." }, "context_hash": { "type": "string", "description": "Present on a leg of a merged multi-platform search: a hash of the topic judged." }, "fresh_ids": { "type": "array", "description": "Present on a leg of a merged multi-platform search: the rows judged afresh on this leg.", "items": { "type": "string", "description": "A row id." } } } }, "walk": { "type": "object", "description": "Present when the request sent a row-walk param (`max_pages` above 1, `max_items`, `max_credits`, a row filter, `sort_rows` or `seen`). What the walk did across the pages it fetched. Each page is billed as one call, and its charge is recorded under its own request id.", "properties": { "pages": { "type": "integer", "description": "Pages fetched.", "example": 3 }, "stopped": { "type": "string", "enum": [ "end", "max_pages", "max_items", "max_credits", "time_budget", "page_error" ], "description": "Why the walk stopped. `end`: the list ran out. `max_pages`, `max_items` or `max_credits`: the limit you set was reached. `time_budget`: the request's time budget ran low. `page_error`: a later page failed. Unless it is `end`, `pagination.next_cursor` continues from where the walk stopped.", "example": "max_pages" }, "rows_fetched": { "type": "integer", "description": "Rows read across every page, before any filter.", "example": 60 }, "rows_returned": { "type": "integer", "description": "Rows in `data.items`.", "example": 41 }, "discarded": { "type": "object", "description": "Present when you sent a row filter. Rows the filters removed, counted once each under the first filter they failed. A row a filter cannot verify (no view count, no date, no country) is discarded.", "properties": { "views_below_min": { "type": "integer", "description": "Rows with fewer views than `min_views`." }, "views_unknown": { "type": "integer", "description": "Rows with no view count, when `min_views` was sent." }, "older_than_max_age": { "type": "integer", "description": "Rows published before the `max_age_days` window." }, "date_unknown": { "type": "integer", "description": "Rows with no publish date, when `max_age_days` was sent." }, "country_not_included": { "type": "integer", "description": "Rows registered to a country that is not in `country`." }, "country_unknown": { "type": "integer", "description": "Rows with no country, when `country` was sent." }, "country_excluded": { "type": "integer", "description": "Rows registered to a country listed in `exclude_country`." } } }, "repeats": { "type": "integer", "description": "Present when you sent `seen`: rows removed because your account already received them under that id." }, "duplicates": { "type": "integer", "description": "Present when above zero: rows a later page repeated from an earlier page of the same walk, kept once." }, "credits": { "type": "object", "description": "What the pages cost.", "properties": { "pages": { "type": "integer", "description": "Credits charged for the pages walked, before refunds." }, "refunded": { "type": "integer", "description": "Credits refunded across the pages." } } }, "request_ids": { "type": "array", "description": "The request id of each page walked. Each is its own entry in `GET /v1/credits/transactions`.", "items": { "type": "string", "description": "A row id." } } } }, "hydration": { "type": "object", "description": "Present when the request asked for a row join with `include=`, or sent a param that implies one. What the join did and what it cost. On a multi-page walk it sums every page. A join that always runs for free is left out.", "properties": { "include": { "type": "string", "description": "The token that switched the join on.", "example": "profile" }, "implied_by": { "type": "string", "description": "Present when you did not send `include` and another param switched the join on. The join's credits (`extra_credits`) are then part of `credits_used`. Absent when you sent `include` yourself." }, "rows": { "type": "integer", "description": "Rows on the page after any row cap.", "example": 20 }, "looked_up": { "type": "integer", "description": "Rows that needed a lookup (at least one field the join fills was empty).", "example": 20 }, "filled": { "type": "integer", "description": "Rows where at least one field was filled by the join.", "example": 18 }, "cached": { "type": "integer", "description": "Of `filled`, rows filled from the sibling endpoint's cache at no charge.", "example": 0 }, "unfilled": { "type": "integer", "description": "Rows that needed a lookup and were not filled (the lookup failed, was skipped, or had nothing to copy). Their credits are refunded.", "example": 2 }, "credits_held": { "type": "integer", "description": "Credits held up front for the join, on top of the page's own price.", "example": 20 }, "extra_credits": { "type": "integer", "description": "Of `credits_held`, the credits kept: one lookup's price for each distinct key filled from a fresh lookup. The rest was refunded.", "example": 18 }, "ms": { "type": "integer", "description": "Time the join added, in milliseconds.", "example": 2400 }, "cached_page": { "type": "boolean", "description": "True when the whole page was served from cache, so the join cost nothing on this call.", "example": true }, "batches": { "type": "integer", "description": "Joins that look rows up in batches only: how many batch calls were made. Absent on a join that looks rows up one by one." }, "from_earlier_pages": { "type": "integer", "description": "`max_pages`, `max_items` and `max_credits` walks only: rows filled free from a key already looked up on an earlier page of the same walk. Not counted in `looked_up`, `filled` or `cached`. Absent when zero." }, "steps": { "type": "array", "description": "Present when the request asked for more than one join (`include=engagement,channel`): one report per join, in the order they ran. The top-level numbers are then the page's: rows looked up or filled by any join, and the credits and time of all of them together.", "items": { "type": "object", "description": "One join's report.", "properties": { "include": { "type": "string", "description": "The token that switched the join on.", "example": "profile" }, "implied_by": { "type": "string", "description": "Present when you did not send `include` and another param switched the join on. The join's credits (`extra_credits`) are then part of `credits_used`. Absent when you sent `include` yourself." }, "rows": { "type": "integer", "description": "Rows on the page after any row cap.", "example": 20 }, "looked_up": { "type": "integer", "description": "Rows that needed a lookup (at least one field the join fills was empty).", "example": 20 }, "filled": { "type": "integer", "description": "Rows where at least one field was filled by the join.", "example": 18 }, "cached": { "type": "integer", "description": "Of `filled`, rows filled from the sibling endpoint's cache at no charge.", "example": 0 }, "unfilled": { "type": "integer", "description": "Rows that needed a lookup and were not filled (the lookup failed, was skipped, or had nothing to copy). Their credits are refunded.", "example": 2 }, "credits_held": { "type": "integer", "description": "Credits held up front for the join, on top of the page's own price.", "example": 20 }, "extra_credits": { "type": "integer", "description": "Of `credits_held`, the credits kept: one lookup's price for each distinct key filled from a fresh lookup. The rest was refunded.", "example": 18 }, "ms": { "type": "integer", "description": "Time the join added, in milliseconds.", "example": 2400 }, "cached_page": { "type": "boolean", "description": "True when the whole page was served from cache, so the join cost nothing on this call.", "example": true }, "batches": { "type": "integer", "description": "Joins that look rows up in batches only: how many batch calls were made. Absent on a join that looks rows up one by one." }, "from_earlier_pages": { "type": "integer", "description": "`max_pages`, `max_items` and `max_credits` walks only: rows filled free from a key already looked up on an earlier page of the same walk. Not counted in `looked_up`, `filled` or `cached`. Absent when zero." } } } } } }, "estimate": { "type": "object", "description": "Present only on a dry run (`dry_run=1`). A dry run charges 0 credits, fetches nothing and returns `data.valid`, `data.normalized_params` and this `estimate` in place of the usual rows. An invalid request is the normal free 400 instead.", "properties": { "kind": { "type": "string", "description": "Always `estimate`.", "example": "estimate" }, "version": { "type": "integer", "description": "The version of this estimate shape.", "example": 1 }, "id": { "type": "string", "description": "The endpoint, as `platform/resource`." }, "method": { "type": "string", "description": "The HTTP method.", "example": "GET" }, "valid": { "type": "boolean", "description": "True when the request would pass every check made before billing.", "example": true }, "hold": { "type": "integer", "description": "Exactly what the router would deduct up front for this request." }, "expected_min": { "type": "integer", "description": "The least a successful call settles at." }, "expected_max": { "type": "integer", "description": "The most a call can settle at. Unused hold is refunded." }, "unit": { "type": "string", "description": "Always `credits`.", "example": "credits" }, "pricing": { "type": "string", "enum": [ "flat", "metered" ], "description": "`flat`: the same price every call. `metered`: the price depends on the work done, and unused hold is refunded.", "example": "flat" }, "formula": { "type": "string", "description": "How the price is worked out, in words." }, "levers": { "type": "array", "description": "Params that change the price, each with the hold for the same request with that one change.", "items": { "type": "object", "description": "One lever.", "properties": { "param": { "type": "string", "description": "The param to change." }, "hold": { "type": "integer", "description": "The hold for the same request with this one change." }, "effect": { "type": "string", "description": "What the change does." } } } }, "cached_likely": { "type": "boolean", "description": "Always false: a dry run does not read the cache.", "example": false }, "normalized_params": { "type": "object", "description": "The params the router prices, after its own normalisation." }, "notes": { "type": "array", "description": "Plain-English notes about this quote.", "items": { "type": "string", "description": "One note." } }, "warnings": { "type": "array", "description": "Notices about the quote, such as a page count that had to be assumed.", "items": { "type": "string", "description": "One notice." } }, "rows_expected": { "type": "integer", "description": "Judged lists only: the most rows one call judges on this endpoint." }, "rows_cached": { "type": "integer", "description": "Judged lists only: rows already judged and free. 0 on a dry run, which sees no rows." }, "label_credits_min": { "type": "integer", "description": "Judged lists only: the least the paid labels add. 0 on a dry run, which sees no rows." }, "label_credits_max": { "type": "integer", "description": "Judged lists only: the most the paid labels can add. 0 when you asked for no paid label." }, "base_credits": { "type": "integer", "description": "Judged lists only: the call's price without the label and relevance holds." } } }, "held_back": { "type": "object", "description": "Present when you sent `fit=goal` with a `goal` and at least one block of the page was not needed for it. The held rows (or fields) stay in place as stubs of `{ id, held: true }`; this block lists them.", "properties": { "ids": { "type": "array", "description": "Ids of the rows or fields that were held back.", "items": { "type": "string", "description": "A row id." } }, "recall": { "type": "string", "description": "A recall id for the full page, which re-reads it from cache at no extra charge.", "example": "fit_3f9a1c0b7d2e4a58" } } }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "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": "facebook", "endpoint": "/v1/facebook/search/groups", "data": { "items": [ { "author": { "id": "user_f84244", "username": null, "display_name": "user_07f0c2", "avatar_url": null, "bio": null, "verified": null, "followers": null, "following": null, "posts_count": null, "likes_count": null, "url": "https://example.com/user_20b8cd", "private": null, "joined_at": null, "ext": { "search_hit": { "match": "group_page", "title": "Sample comment text (redacted).", "snippet": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "evidence_url": "https://example.com/user_20b8cd" } } }, "computed": { "relevance": { "p": 0.93, "sense": "target", "depth": 2.8, "spam": 0.36 } } }, { "author": { "id": "user_3e33a9", "username": null, "display_name": null, "avatar_url": null, "bio": null, "verified": null, "followers": null, "following": null, "posts_count": null, "likes_count": null, "url": "https://example.com/user_180d85", "private": null, "joined_at": null, "ext": { "search_hit": { "match": "post_in_group", "title": "Sample comment text (redacted).", "snippet": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).", "evidence_url": "https://example.com/user_1ba3ba" } } }, "computed": { "relevance": { "p": 0.96, "sense": "target", "depth": 2.99, "spam": 0.13 } } } ], "total": null, "relevance": { "mode": "score", "topic_source": "query", "rows": 10, "scored": 10, "cached": 5, "kept": 10, "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" }, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiMiIsImUiOiJmYWNlYm9vay9zZWFyY2gvZ3JvdXBzIiwicCI6InBhZ2UifQ", "has_more": true, "page_size": 10 }, "credits_remaining": 9999 } } } }, "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" } } } } } } }, "/facebook/search/hashtag": { "get": { "summary": "Search Facebook posts and videos carrying a hashtag", "description": "Returns public Facebook posts and videos that carry one hashtag. Facebook's video search matches a hashtag and its post search mostly matches the word, so each call runs both, /v1/facebook/search/videos for `#tag` and /v1/facebook/search/posts for `#tag` ranked by recency, and keeps only the rows whose text carries the exact hashtag (`#tractor` leaves out `#tractorlife` and the bare word). Rows are merged newest first, undated rows last, and a post found by both searches appears once. Each row in `data.items` is exactly the row the named search endpoint returns, with its `post` and `computed` blocks, plus `match_kind` (`hashtag`). Video rows carry what /v1/facebook/search/videos carries, so on a call without dates their counts and publish time are null. `since` and `until` are sent as each search's `start_date` and `end_date`, and because Facebook's video card carries no date, a call with either one also looks up each video's details (`include=details`): every video then carries its publish time and counts, a video outside the window is left out, and one that still could not be dated is left out and counted in `data.excluded.undated`. Send `data.next_cursor` back as `cursor` for the next page; it is null when every search has run out. `data.legs` reports each search: its endpoint, status, rows returned and kept, credits and `request_id`. `data.excluded` counts the rows left out (`unmatched`, `self`, `duplicate`, `outside_window`). Each call is one page of each search, 1 credit each, so at most 2; with `since` or `until` the video page also bills 1 credit per video looked up (7 a page), so at most 9.", "tags": [ "facebook" ], "operationId": "get_facebook_search_hashtag", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 0, "x-credit-cost-min": 0, "x-credit-cost-max": 9, "x-credit-cost-formula": "Metered, 0-9 credits: each call reads one page of /v1/facebook/search/videos (1 credit; with `since` or `until`, up to 8, since each video is looked up for its publish date at 1 credit, and a video still undated is left out) and /v1/facebook/search/posts (1 credit), each billed at that endpoint's own price exactly as a direct call is. A page that found nothing or failed costs nothing, and a page served from cache is free. A page is billed when it returned rows, even if none of them carried the hashtag; data.legs shows each page's charge and data.excluded what was left out.", "parameters": [ { "name": "hashtag", "in": "query", "required": true, "description": "One hashtag, with or without the #: letters, digits and _, no spaces.", "schema": { "type": "string" }, "example": "tractor" }, { "name": "cursor", "in": "query", "required": false, "description": "data.next_cursor from the previous response, sent back verbatim for the next page.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only posts published on or after this date, YYYY-MM-DD (UTC).", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only posts published on or before this date, YYYY-MM-DD (UTC); that whole day is included.", "schema": { "type": "string" } }, { "name": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 120 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 120 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/search/hashtag" }, "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 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached" ] }, "example": { "success": true, "platform": "instagram", "endpoint": "/v1/instagram/engagement", "data": { "engagement_rate_percentages": 38.33, "recent_posts": 12, "followers": 87608035, "comments": 528912, "likes": 33049046, "recent_posts_explanation": "Statistics based on the last 12 posts", "id_user": "2278169415", "username": "mrbeast", "is_private": false, "posts_details": [ { "likes": 5636982, "comments": 69484, "taken_at": 1781457954, "datetime": "2026-06-14 20:25:54", "hours_since_post": 461, "time_ago": "19 days ago", "likes_per_hour": 12228, "comments_per_hour": 151 }, { "likes": 20000768, "comments": 223510, "taken_at": 1732824650, "datetime": "2024-11-28 23:10:50", "hours_since_post": 13971, "time_ago": "2 years ago", "likes_per_hour": 1432, "comments_per_hour": 16 }, { "likes": 929226, "comments": 30633, "taken_at": 1782232475, "datetime": "2026-06-23 19:34:35", "hours_since_post": 246, "time_ago": "10 days ago", "likes_per_hour": 3777, "comments_per_hour": 125 }, { "likes": 487761, "comments": 22482, "taken_at": 1781799425, "datetime": "2026-06-18 19:17:05", "hours_since_post": 366, "time_ago": "15 days ago", "likes_per_hour": 1333, "comments_per_hour": 61 }, { "likes": 712265, "comments": 15716, "taken_at": 1781366405, "datetime": "2026-06-13 19:00:05", "hours_since_post": 487, "time_ago": "20 days ago", "likes_per_hour": 1463, "comments_per_hour": 32 }, { "likes": 1475116, "comments": 35386, "taken_at": 1781277094, "datetime": "2026-06-12 18:11:34", "hours_since_post": 512, "time_ago": "21 days ago", "likes_per_hour": 2881, "comments_per_hour": 69 }, { "likes": 1108220, "comments": 26632, "taken_at": 1780160249, "datetime": "2026-05-30 19:57:29", "hours_since_post": 822, "time_ago": "1 months ago", "likes_per_hour": 1348, "comments_per_hour": 32 }, { "likes": 542948, "comments": 28476, "taken_at": 1779375582, "datetime": "2026-05-21 17:59:42", "hours_since_post": 1040, "time_ago": "1 months ago", "likes_per_hour": 522, "comments_per_hour": 27 }, { "likes": 698514, "comments": 24401, "taken_at": 1779120014, "datetime": "2026-05-18 19:00:14", "hours_since_post": 1111, "time_ago": "2 months ago", "likes_per_hour": 629, "comments_per_hour": 22 }, { "likes": 468000, "comments": 13548, "taken_at": 1778947209, "datetime": "2026-05-16 19:00:09", "hours_since_post": 1159, "time_ago": "2 months ago", "likes_per_hour": 404, "comments_per_hour": 12 }, { "likes": 526594, "comments": 24411, "taken_at": 1777737719, "datetime": "2026-05-02 19:01:59", "hours_since_post": 1495, "time_ago": "2 months ago", "likes_per_hour": 352, "comments_per_hour": 16 }, { "likes": 462652, "comments": 14233, "taken_at": 1777580305, "datetime": "2026-04-30 23:18:25", "hours_since_post": 1538, "time_ago": "2 months ago", "likes_per_hour": 301, "comments_per_hour": 9 } ] }, "credits_used": 5, "credits_remaining": 9999, "request_id": "req-8Kq2ZmR4vT9xLb3P", "cached": false } } } }, "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" } } } } } } }, "/facebook/search/mentions": { "get": { "summary": "Search Facebook posts that mention a page", "description": "Returns public Facebook posts by other people and pages that mention a page. Facebook links a mention by the page's name, not an @handle, so the search is the page's name on /v1/facebook/search/posts, newest first (`name`, which defaults to `handle`), and each row is kept only when its text names the page (the whole word, any case), @mentions the handle, or links the page. The page's own posts are left out unless `include_self=true`. Each row in `data.items` is exactly the row the named search endpoint returns, with its `post` and `computed` blocks, plus `match_kind` (`mention` or `link`). `since` and `until` are sent as the search's `start_date` and `end_date`. Send `data.next_cursor` back as `cursor` for the next page; it is null when every search has run out. `data.legs` reports each search: its endpoint, status, rows returned and kept, credits and `request_id`. `data.excluded` counts the rows left out (`unmatched`, `self`, `duplicate`, `outside_window`). Each page is one /v1/facebook/search/posts page, 1 credit.", "tags": [ "facebook" ], "operationId": "get_facebook_search_mentions", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 0, "x-credit-cost-min": 0, "x-credit-cost-max": 1, "x-credit-cost-formula": "Metered, 0-1 credits: each call reads one page of /v1/facebook/search/posts (1 credit), each billed at that endpoint's own price exactly as a direct call is. A page that found nothing or failed costs nothing, and a page served from cache is free. A page is billed when it returned rows, even if none of them carried the mention; data.legs shows each page's charge and data.excluded what was left out.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "The page's username (facebook.com/), with or without the @, or its URL. Used to leave out the page's own posts.", "schema": { "type": "string" }, "example": "myntra" }, { "name": "cursor", "in": "query", "required": false, "description": "data.next_cursor from the previous response, sent back verbatim for the next page.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only posts published on or after this date, YYYY-MM-DD (UTC).", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only posts published on or before this date, YYYY-MM-DD (UTC); that whole day is included.", "schema": { "type": "string" } }, { "name": "name", "in": "query", "required": false, "description": "The name people write when they mention the page, for example Nykaa for facebook.com/mynykaa. Defaults to handle.", "schema": { "type": "string" } }, { "name": "include_self", "in": "query", "required": false, "description": "When true, also keep posts by the account itself. Default false.", "schema": { "type": "boolean" } }, { "name": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 120 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 120 } }, { "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. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. 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": "facebook" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/facebook/search/mentions" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "metrics": { "type": "object", "description": "Key performance metrics", "properties": { "total_views": { "type": "integer", "description": "Total view count" }, "total_likes": { "type": "integer", "description": "Total like count" }, "total_comments": { "type": "integer", "description": "Total comment count" }, "engagement_rate": { "type": "number", "description": "Computed engagement rate (0-1)" } } }, "period": { "type": [ "string", "null" ], "description": "Time period for the analytics data" }, "breakdown": { "type": [ "array", "null" ], "description": "Per-item or per-period breakdown", "items": { "type": "object", "description": "Breakdown entry" } }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } } }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "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 }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached" ] }, "example": { "success": true, "platform": "instagram", "endpoint": "/v1/instagram/engagement", "data": { "engagement_rate_percentages": 38.33, "recent_posts": 12, "followers": 87608035, "comments": 528912, "likes": 33049046, "recent_posts_explanation": "Statistics based on the last 12 posts", "id_user": "2278169415", "username": "mrbeast", "is_private": false, "posts_details": [ { "likes": 5636982, "comments": 69484, "taken_at": 1781457954, "datetime": "2026-06-14 20:25:54", "hours_since_post": 461, "time_ago": "19 days ago", "likes_per_hour": 12228, "comments_per_hour": 151 }, { "likes": 20000768, "comments": 223510, "taken_at": 1732824650, "datetime": "2024-11-28 23:10:50", "hours_since_post": 13971, "time_ago": "2 years ago", "likes_per_hour": 1432, "comments_per_hour": 16 }, { "likes": 929226, "comments": 30633, "taken_at": 1782232475, "datetime": "2026-06-23 19:34:35", "hours_since_post": 246, "time_ago": "10 days ago", "likes_per_hour": 3777, "comments_per_hour": 125 }, { "likes": 487761, "comments": 22482, "taken_at": 1781799425, "datetime": "2026-06-18 19:17:05", "hours_since_post": 366, "time_ago": "15 days ago", "likes_per_hour": 1333, "comments_per_hour": 61 }, { "likes": 712265, "comments": 15716, "taken_at": 1781366405, "datetime": "2026-06-13 19:00:05", "hours_since_post": 487, "time_ago": "20 days ago", "likes_per_hour": 1463, "comments_per_hour": 32 }, { "likes": 1475116, "comments": 35386, "taken_at": 1781277094, "datetime": "2026-06-12 18:11:34", "hours_since_post": 512, "time_ago": "21 days ago", "likes_per_hour": 2881, "comments_per_hour": 69 }, { "likes": 1108220, "comments": 26632, "taken_at": 1780160249, "datetime": "2026-05-30 19:57:29", "hours_since_post": 822, "time_ago": "1 months ago", "likes_per_hour": 1348, "comments_per_hour": 32 }, { "likes": 542948, "comments": 28476, "taken_at": 1779375582, "datetime": "2026-05-21 17:59:42", "hours_since_post": 1040, "time_ago": "1 months ago", "likes_per_hour": 522, "comments_per_hour": 27 }, { "likes": 698514, "comments": 24401, "taken_at": 1779120014, "datetime": "2026-05-18 19:00:14", "hours_since_post": 1111, "time_ago": "2 months ago", "likes_per_hour": 629, "comments_per_hour": 22 }, { "likes": 468000, "comments": 13548, "taken_at": 1778947209, "datetime": "2026-05-16 19:00:09", "hours_since_post": 1159, "time_ago": "2 months ago", "likes_per_hour": 404, "comments_per_hour": 12 }, { "likes": 526594, "comments": 24411, "taken_at": 1777737719, "datetime": "2026-05-02 19:01:59", "hours_since_post": 1495, "time_ago": "2 months ago", "likes_per_hour": 352, "comments_per_hour": 16 }, { "likes": 462652, "comments": 14233, "taken_at": 1777580305, "datetime": "2026-04-30 23:18:25", "hours_since_post": 1538, "time_ago": "2 months ago", "likes_per_hour": 301, "comments_per_hour": 9 } ] }, "credits_used": 5, "credits_remaining": 9999, "request_id": "req-8Kq2ZmR4vT9xLb3P", "cached": false } } } }, "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" }