{ "openapi": "3.1.0", "info": { "title": "SocialCrawl API: Google", "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 Google endpoints only (12 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": "google", "description": "Google endpoints" } ], "paths": { "/google/search": { "get": { "summary": "Google web search", "description": "Returns Google search results for a query. Each result includes title, URL, and a text snippet. Google's own operators work in the query: `site:theqoo.net 다한증` returns only pages from that site (measured 09/10/2026: every row on the named domain), which makes this the cheapest way to find posts on one forum or community before reading them with /v1/web/scrape. Ten results a page; `page` walks further.", "tags": [ "google" ], "operationId": "get_google_search", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search keyword or phrase. Google operators such as site:example.com work.", "schema": { "type": "string" }, "example": "best restaurants in London" }, { "name": "region", "in": "query", "required": false, "description": "2 letter country code, ie US, UK, CA, KR, etc This will show results from that country", "schema": { "type": "string" } }, { "name": "date_posted", "in": "query", "required": false, "description": "Only pages Google dates within this window: last-hour, last-day, last-week, last-month or last-year. The strongest recency filter for forum and community posts.", "schema": { "type": "string", "enum": [ "last-hour", "last-day", "last-week", "last-month", "last-year" ] } }, { "name": "page", "in": "query", "required": false, "description": "Page number to retrieve Native upstream cursor param. Send the universal `cursor` instead: the API maps it to this name for you.", "deprecated": true, "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": "google" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/google/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": "google", "endpoint": "/v1/google/search", "data": { "items": [ { "title": "My Top 50 London Restaurants (2026 Edition) - Angus Colwell Food", "url": "https://anguscolwell.substack.com/p/my-top-50-london-restaurants-2026", "description": "Feb 4, 2026 ... My Top 50 London Restaurants (2026 Edition) · Or: What I got Wrong About Ranking Restaurants · 50) Sông Quê, Hoxton · 49) ECCo Pizza, ..." }, { "title": "Steal My Food Itinerary: 3 Days in London | Eater", "url": "https://www.eater.com/dining-out/975009/restaurant-recommendations-london-steal-my-3-day-itinerary", "description": "Jul 22, 2026 ... No restaurant was recommended to me more frequently or enthusiastically than Mountain, the Basque-inspired Soho restaurant from chef Tomos Parry ..." } ], "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiMiIsImUiOiJnb29nbGUvc2VhcmNoIiwicCI6InBhZ2UiLCJzIjoiYiJ9", "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" } } } } } } }, "/google/ad": { "get": { "summary": "Get Google ad details", "description": "Returns detailed information about a specific Google advertisement including ad copy, advertiser, and format.", "tags": [ "google" ], "operationId": "get_google_ad", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Ads Transparency Center CREATIVE URL: must include both the advertiser and creative segments (`…/advertiser/{AR…}/creative/{CR…}`). Get one from `/v1/google/company/ads`.", "schema": { "type": "string" }, "example": "https://adstransparency.google.com/advertiser/AR01614014350098432001/creative/CR04647239345386815489" }, { "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": "google" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/google/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": "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" } } } } } } }, "/google/adlibrary/advertisers/search": { "get": { "summary": "Search Google Ad Library advertisers", "description": "Searches the Google Ads Transparency Center for advertisers matching a query. Returns matching advertisers with `name`, `advertiser_id`, and `region`, plus their website domains. Defaults to US when `region` is omitted: pass a 2-letter country code (e.g. `AU`, `CA`) to search advertisers in another region.", "tags": [ "google" ], "operationId": "get_google_adlibrary_advertisers_search", "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 advertisers in the Google Ads Transparency Center.", "schema": { "type": "string" }, "example": "lululemon" }, { "name": "region", "in": "query", "required": false, "description": "2-letter country code to search in. Defaults to US.", "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": "google" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/google/adlibrary/advertisers/search" }, "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" } } } } } } }, "/google/company/ads": { "get": { "summary": "List Google ads by company", "description": "Returns ads from a specific company/domain in the Google Ads Transparency Center. Each ad includes creative, format, and date range.", "tags": [ "google" ], "operationId": "get_google_company_ads", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "x-socialcrawl-oneOf": [ [ "domain", "advertiser_id" ] ], "parameters": [ { "name": "domain", "in": "query", "required": false, "description": "Company domain name to look up ads for (one of: domain, advertiser_id; at least one required)", "schema": { "type": "string" }, "example": "lululemon.com" }, { "name": "advertiser_id", "in": "query", "required": false, "description": "The advertiser id of the company (one of: domain, advertiser_id; at least one required)", "schema": { "type": "string" } }, { "name": "topic", "in": "query", "required": false, "description": "The topic to search for. If you search for 'political', you will also need to pass a 'region', like 'US' or 'AU'", "schema": { "type": "string", "enum": [ "all", "political" ] } }, { "name": "region", "in": "query", "required": false, "description": "The region to search for. Defaults to anywhere", "schema": { "type": "string" } }, { "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": "platform", "in": "query", "required": false, "description": "Google surface to filter ads by (e.g. youtube, google_search)", "schema": { "type": "string", "enum": [ "google_maps", "google_play", "google_search", "google_shopping", "youtube" ] } }, { "name": "format", "in": "query", "required": false, "description": "Ad format to filter by: text, image, or video", "schema": { "type": "string", "enum": [ "text", "image", "video" ] } }, { "name": "get_ad_details", "in": "query", "required": false, "description": "Set to true to get the ad details. Will cost 25 credits.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor to paginate through results", "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 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": "google" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/google/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." } } } }, "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": "google", "endpoint": "/v1/google/company/ads", "data": { "items": [ { "post": { "id": "CR10103153352515780609", "url": "https://adstransparency.google.com/advertiser/AR01614014350098432001/creative/CR10103153352515780609", "content": { "text": "Sample comment text (redacted).", "media_urls": null, "thumbnail_url": null, "duration_seconds": null }, "author": { "username": "user_00997a", "display_name": "user_00997a", "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-08-20T17:25:21.000Z" }, "computed": { "engagement_rate": null, "language": null, "content_category": "other", "estimated_reach": null } }, { "post": { "id": "CR06570150526552375297", "url": "https://adstransparency.google.com/advertiser/AR01614014350098432001/creative/CR06570150526552375297", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://tpc.googlesyndication.com/archive/simgad/16312224302241590379", "thumbnail_url": "https://tpc.googlesyndication.com/archive/simgad/16312224302241590379", "duration_seconds": null }, "author": { "username": "user_00997a", "display_name": "user_00997a", "avatar_url": null, "verified": null }, "engagement": { "views": null, "likes": null, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2024-03-02T00:01:53.000Z" }, "computed": { "engagement_rate": null, "language": null, "content_category": "other", "estimated_reach": null } } ], "next_cursor": "CgoAP7zmjKtTr6dPEhCRsQTh%2BlkqOj%2B8f%2B4AAAAAGgn8%2BGi5%2BIy4k7o%3D", "total": null, "dropped": 0 }, "credits_used": 5, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiQ2dvQVA3em1qS3RUcjZkUEVoQ1JzUVRoJTJCbGtxT2olMkI4ZiUyQjRBQUFBQUdnbjglMkJHaTUlMkJJeTRrN28lM0QiLCJlIjoiZ29vZ2xlL2NvbXBhbnkvYWRzIiwicCI6ImN1cnNvciJ9", "has_more": true, "page_size": 40 }, "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" } } } } } } }, "/google/business/info": { "get": { "summary": "Get a Google Business Profile", "description": "Returns the full Google Business Profile (Maps / Knowledge Panel) for a local business: name, category, rating, address, phone, coordinates, hours, attributes, and claimed status. Identify the place by keyword, cid, or place_id (cid/place_id are most reliable). A lookup by keyword alone can come back without `ext.attributes`, `ext.people_also_search` and `ext.status`; pass cid or place_id for the complete profile.", "tags": [ "google" ], "operationId": "get_google_business_info", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-socialcrawl-oneOf": [ [ "keyword", "cid", "place_id" ] ], "parameters": [ { "name": "keyword", "in": "query", "required": false, "description": "Business name + address (e.g. 'Irving Farm New York 645 5th Ave'). Use cid/place_id when known for an exact match. (one of: keyword, cid, place_id; at least one required)", "schema": { "type": "string" }, "example": "Irving Farm New York 645 5th Ave" }, { "name": "cid", "in": "query", "required": false, "description": "Google customer id (cid) of the place: the most reliable identifier. (one of: keyword, cid, place_id; at least one required)", "schema": { "type": "string" } }, { "name": "place_id", "in": "query", "required": false, "description": "Google place_id of the place. (one of: keyword, cid, place_id; at least one required)", "schema": { "type": "string" } }, { "name": "location_name", "in": "query", "required": false, "description": "Geographic context as 'City,Region,Country'. Without it, a keyword that looks Polish (a Polish postcode or Polish-only letters) is searched in Poland and every other keyword in 'New York,New York,United States'.", "schema": { "type": "string" } }, { "name": "language_name", "in": "query", "required": false, "description": "Result language (default 'English').", "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": "google" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/google/business/info" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "place": { "type": "object", "description": "Canonical Place object (physical/local business or hotel)", "properties": { "id": { "type": "string", "description": "Place ID (Google cid for a business, hotel_identifier for a hotel)" }, "name": { "type": [ "string", "null" ], "description": "Business / hotel name" }, "url": { "type": [ "string", "null" ], "description": "Website or canonical URL" }, "category": { "type": [ "string", "null" ], "description": "Primary category (e.g. \"Coffee shop\", \"Hotel\")" }, "rating": { "type": "object", "description": "Aggregate rating (value + max)", "properties": { "value": { "type": [ "number", "null" ], "description": "Numeric at place.rating.value" }, "max": { "type": [ "number", "null" ], "description": "Numeric at place.rating.max" } } }, "reviews_count": { "type": [ "number", "null" ], "description": "Number of ratings" }, "price_level": { "type": [ "string", "null" ], "description": "Price band (\"inexpensive\" / \"$$\" / null)" }, "address": { "type": [ "string", "null" ], "description": "String at place.address" }, "phone": { "type": [ "string", "null" ], "description": "String at place.phone" }, "latitude": { "type": [ "number", "null" ], "description": "Numeric at place.latitude" }, "longitude": { "type": [ "number", "null" ], "description": "Numeric at place.longitude" }, "verified": { "type": [ "boolean", "null" ], "description": "Claimed-business flag (Google is_claimed)" }, "description": { "type": [ "string", "null" ], "description": "String at place.description" }, "image_urls": { "type": [ "string", "array", "null" ], "description": "Union: string | array | null", "items": { "type": "string", "description": "String at place.image_urls" } }, "categories": { "type": [ "array", "null" ], "description": "Array at place.categories", "items": { "type": "string", "description": "String at place.categories" } }, "hotel": { "type": [ "object", "null" ], "description": "Hotel-only richness (stars, amenities, review topics, prices); null for plain places", "properties": { "stars": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.stars" }, "stars_description": { "type": [ "string", "null" ], "description": "String at place.hotel.stars_description" }, "check_in_time": { "type": [ "string", "null" ], "description": "String at place.hotel.check_in_time" }, "check_out_time": { "type": [ "string", "null" ], "description": "String at place.hotel.check_out_time" }, "amenities": { "type": [ "array", "null" ], "description": "Array at place.hotel.amenities", "items": { "type": "object", "description": "Nested object: place.hotel.amenities", "properties": { "category": { "type": [ "string", "null" ], "description": "String at place.hotel.amenities.category" }, "name": { "type": [ "string", "null" ], "description": "String at place.hotel.amenities.name" }, "available": { "type": [ "boolean", "null" ], "description": "Boolean at place.hotel.amenities.available" }, "hint": { "type": [ "string", "null" ], "description": "String at place.hotel.amenities.hint" } } } }, "review_topics": { "type": [ "array", "null" ], "description": "Array at place.hotel.review_topics", "items": { "type": "object", "description": "Nested object: place.hotel.review_topics", "properties": { "title": { "type": [ "string", "null" ], "description": "String at place.hotel.review_topics.title" }, "positive_score": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.review_topics.positive_score" }, "positive_count": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.review_topics.positive_count" }, "negative_count": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.review_topics.negative_count" }, "total_count": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.review_topics.total_count" } } } }, "prices": { "type": [ "array", "null" ], "description": "Array at place.hotel.prices", "items": { "type": "object", "description": "Nested object: place.hotel.prices", "properties": { "title": { "type": [ "string", "null" ], "description": "String at place.hotel.prices.title" }, "price": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.prices.price" }, "currency": { "type": [ "string", "null" ], "description": "String at place.hotel.prices.currency" }, "url": { "type": [ "string", "null" ], "description": "String at place.hotel.prices.url" }, "official_site": { "type": [ "boolean", "null" ], "description": "Boolean at place.hotel.prices.official_site" } } } } } }, "ext": { "type": [ "object", "null" ], "description": "Nested object: place.ext", "properties": { "distance": { "type": [ "number", "null" ], "description": "Numeric at place.ext.distance" }, "status": { "type": [ "string", "null" ], "description": "String at place.ext.status" }, "timezone": { "type": [ "string", "null" ], "description": "String at place.ext.timezone" }, "hours": { "type": [ "array", "null" ], "description": "Array at place.ext.hours", "items": { "type": "object", "description": "Nested object: place.ext.hours", "properties": { "date": { "type": [ "string", "null" ], "description": "String at place.ext.hours.date" }, "day_name": { "type": [ "string", "null" ], "description": "String at place.ext.hours.day_name" }, "is_open": { "type": [ "boolean", "null" ], "description": "Boolean at place.ext.hours.is_open" }, "opens_at": { "type": [ "string", "null" ], "description": "String at place.ext.hours.opens_at" }, "closes_at": { "type": [ "string", "null" ], "description": "String at place.ext.hours.closes_at" } } } }, "place_id": { "type": [ "string", "null" ], "description": "String at place.ext.place_id" }, "attributes": { "type": [ "object", "null" ], "description": "Object at place.ext.attributes" }, "rating_distribution": { "type": [ "object", "null" ], "description": "Object at place.ext.rating_distribution", "additionalProperties": { "type": "number", "description": "Numeric at place.ext.rating_distribution.*" } }, "people_also_search": { "type": [ "array", "null" ], "description": "Array at place.ext.people_also_search", "items": { "type": "object", "description": "Nested object: place.ext.people_also_search", "properties": { "cid": { "type": [ "string", "null" ], "description": "String at place.ext.people_also_search.cid" }, "title": { "type": [ "string", "null" ], "description": "String at place.ext.people_also_search.title" }, "rating": { "type": [ "object", "null" ], "description": "Nested object: place.ext.people_also_search.rating", "properties": { "value": { "type": [ "number", "null" ], "description": "Numeric at place.ext.people_also_search.rating.value" }, "votes_count": { "type": [ "number", "null" ], "description": "Numeric at place.ext.people_also_search.rating.votes_count" } } } } } }, "menu_url": { "type": [ "string", "null" ], "description": "String at place.ext.menu_url" }, "domain": { "type": [ "string", "null" ], "description": "String at place.ext.domain" }, "maps_url": { "type": [ "string", "null" ], "description": "String at place.ext.maps_url" }, "rank": { "type": [ "number", "null" ], "description": "Numeric at place.ext.rank" }, "city": { "type": [ "string", "null" ], "description": "String at place.ext.city" }, "postal_code": { "type": [ "string", "null" ], "description": "String at place.ext.postal_code" }, "region": { "type": [ "string", "null" ], "description": "String at place.ext.region" }, "country_code": { "type": [ "string", "null" ], "description": "String at place.ext.country_code" }, "posts_count": { "type": [ "number", "null" ], "description": "`/v1/instagram/location` only: the number of public posts Instagram counts at the place." }, "website": { "type": [ "string", "null" ], "description": "`/v1/instagram/location` only: the venue's own website (`place.url` is its Instagram page)." }, "facebook_places_id": { "type": [ "string", "null" ], "description": "`/v1/instagram/location` only: the Facebook Places id of the same place." }, "business_username": { "type": [ "string", "null" ], "description": "`/v1/instagram/location` only: the username of the Instagram business account linked to the place, or null when none is linked." }, "is_ad": { "type": [ "boolean", "null" ], "description": "Boolean at place.ext.is_ad" }, "ad_rank": { "type": [ "number", "null" ], "description": "Numeric at place.ext.ad_rank" }, "ad_description": { "type": [ "string", "null" ], "description": "String at place.ext.ad_description" }, "status_description": { "type": [ "string", "null" ], "description": "String at place.ext.status_description" }, "visitor_reviews_count": { "type": [ "number", "null" ], "description": "Numeric at place.ext.visitor_reviews_count" }, "blog_reviews_count": { "type": [ "number", "null" ], "description": "Numeric at place.ext.blog_reviews_count" }, "booking_url": { "type": [ "string", "null" ], "description": "String at place.ext.booking_url" }, "keywords": { "type": [ "array", "null" ], "description": "Array at place.ext.keywords", "items": { "type": "string", "description": "String at place.ext.keywords" } } } } } }, "_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": [ "place" ] }, "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": "google", "endpoint": "/v1/google/business/info", "data": { "place": { "id": "10008150968882388764", "name": "Irving Farm New York", "url": "http://irvingfarm.com/", "category": "Coffee shop", "rating": { "value": 4.3, "max": 5 }, "reviews_count": 19, "price_level": null, "address": "645 5th Ave, New York, NY 10022", "phone": "+12122060707", "latitude": 40.7594343, "longitude": -73.9757835, "verified": true, "description": "Hip local coffee house chain serving light eats & drinks made from house-roasted beans.", "image_urls": "https://lh3.googleusercontent.com/gps-cs-s/AHRPTWnjAcwpFOt-lN1AFR11h4yfJKoIu4TBCXalnU9Ew5Hrci9PzNwBi5DaL5QTX-3pl2X2Jo3JyrgKOTHyh9CMLsK0sC_hPdyjOwmQWBC2IS-EGqzxvndSrItHKYbSMLE0F02NuFT0g4wLlr_R=w408-h544-k-no", "categories": [ "Breakfast restaurant", "Brunch restaurant" ], "ext": { "hours": [ { "date": null, "day_name": "monday", "is_open": true, "opens_at": "08:00", "closes_at": "16:00" }, { "date": null, "day_name": "tuesday", "is_open": true, "opens_at": "08:00", "closes_at": "16:00" } ], "place_id": "ChIJhXVzs1RZwokRHF-33kcY5Io", "rating_distribution": { "1": 1, "2": 1, "3": 1, "4": 4, "5": 12 } } } }, "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" } } } } } } }, "/google/business/extended-reviews": { "get": { "summary": "Get Google extended (multi-source) reviews", "description": "Returns reviews of a place aggregated from the Google reviews element, not only Google users but reputable third-party sources (TripAdvisor, Yelp, Trustpilot). Each review carries its source domain, full text (with original-language translation), star rating, reviewer stats, and owner replies. Identify the place by keyword, cid, or place_id.", "tags": [ "google" ], "operationId": "get_google_business_extended_reviews", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "x-credit-cost-min": 5, "x-credit-cost-max": 9, "x-credit-cost-formula": "5 credits per page. The default labels (sentiment, issue) are free. label=reports, incentivized or injection holds 4 extra credits and refunds down to 1 credit per started 25 reviews that were newly judged (the first 100 reviews of a page are judged): reviews already labelled are free, a page where nothing could be judged refunds the whole extra, and a cached page is free.", "x-socialcrawl-oneOf": [ [ "keyword", "cid", "place_id" ] ], "parameters": [ { "name": "keyword", "in": "query", "required": false, "description": "Business name + address. Use cid/place_id for an exact match. (one of: keyword, cid, place_id; at least one required)", "schema": { "type": "string" }, "example": "Irving Farm New York 645 5th Ave" }, { "name": "cid", "in": "query", "required": false, "description": "Google customer id (cid) of the place. (one of: keyword, cid, place_id; at least one required)", "schema": { "type": "string" } }, { "name": "place_id", "in": "query", "required": false, "description": "Google place_id of the place. (one of: keyword, cid, place_id; at least one required)", "schema": { "type": "string" } }, { "name": "location_name", "in": "query", "required": false, "description": "Geographic context as 'City,Region,Country'.", "schema": { "type": "string" } }, { "name": "language_name", "in": "query", "required": false, "description": "Result language (default 'English').", "schema": { "type": "string" } }, { "name": "depth", "in": "query", "required": false, "description": "Number of reviews to return (default 20, step 20, max 1000).", "schema": { "type": "integer" } }, { "name": "label", "in": "query", "required": false, "description": "Optional CSV of SocialCrawl labels to add to every review. Without this param every page already carries sentiment and issue, free; label= adds the labels you name to them (the defaults keep running). sentiment and issue are free when asked for too; reports, incentivized and injection add 1 credit per started 25 newly judged reviews. judgments=off (or label=none) turns the default labels off. They read the review's title and text, never its stars. sentiment: how the reviewer feels, on five levels (level 0 to 4, score_0_1, confidence), plus rating_mismatch, true when the words clearly contradict the star rating (a glowing text under 1 star, a furious one under 5), null when the review has no rating. issue: the main problem the review reports (label: product_defect, sizing_or_fit, shipping_or_delivery, customer_service, price_or_value, missing_feature, other, or none, with confidence; label is null when unsure). reports (needs reports=): does this review say that the thing you describe happened (p, 0 to 1). incentivized: does the reviewer say they got the product free, discounted or rewarded for the review (p), and did the text carry a disclosure such as 'in exchange for my honest review', Vine or 체험단 (disclosed). injection flags text that addresses an AI system and tries to direct it (flagged, p); it never drops or rewrites a row. These are signals to read, never a verdict on a review or a reviewer. A review that could not be judged carries labels: null. Reviews already labelled for anyone are free, and so is a cached page. data.labels reports what was judged and billed.", "schema": { "type": "string" } }, { "name": "reports", "in": "query", "required": false, "description": "Required by label=reports, ignored otherwise. What to look for, in plain words, up to 300 characters, for example reports=the battery drains quickly or reports=배송이 늦음. Every review gains labels.reports.p, the probability that it says so, in any wording or language. Without it label=reports is skipped with the warning label_reports_needs_reports and is not billed.", "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_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": "google" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/google/business/extended-reviews" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical review wrappers ({ review })", "items": { "type": "object", "description": "Canonical review wrapper", "properties": { "review": { "type": "object", "description": "Canonical Review object (shared across commerce platforms)", "properties": { "id": { "type": "string", "description": "Review ID (parsed from the review URL when not first-class)" }, "entity_id": { "type": [ "string", "null" ], "description": "ID of the reviewed entity (e.g. the Amazon ASIN)" }, "url": { "type": [ "string", "null" ], "description": "String at review.url" }, "title": { "type": [ "string", "null" ], "description": "String at review.title" }, "text": { "type": [ "string", "null" ], "description": "Full review body" }, "rating": { "type": "object", "description": "Star rating (value + max)", "properties": { "value": { "type": [ "number", "null" ], "description": "Numeric at review.rating.value" }, "max": { "type": [ "number", "null" ], "description": "Numeric at review.rating.max" } } }, "author": { "type": "object", "description": "Nested object: review.author", "properties": { "name": { "type": [ "string", "null" ], "description": "String at review.author.name" }, "avatar_url": { "type": [ "string", "null" ], "description": "String at review.author.avatar_url" }, "url": { "type": [ "string", "null" ], "description": "String at review.author.url" }, "location": { "type": [ "string", "null" ], "description": "String at review.author.location" }, "reviews_count": { "type": [ "number", "null" ], "description": "Numeric at review.author.reviews_count" } } }, "helpful_votes": { "type": [ "number", "null" ], "description": "Helpful-vote count (Amazon; null elsewhere)" }, "verified": { "type": [ "boolean", "null" ], "description": "Verified-purchase flag (Amazon; null elsewhere)" }, "source": { "type": [ "string", "null" ], "description": "String at review.source" }, "language": { "type": [ "string", "null" ], "description": "String at review.language" }, "original_language": { "type": [ "string", "null" ], "description": "String at review.original_language" }, "translated": { "type": [ "boolean", "null" ], "description": "Boolean at review.translated" }, "images": { "type": [ "array", "null" ], "description": "Array at review.images", "items": { "type": "string", "description": "String at review.images" } }, "responses": { "type": [ "array", "null" ], "description": "Owner/brand/management replies to the review, each `{id, author, text, published_at}` with `published_at` as an ISO 8601 UTC string (REL-07.6).", "items": { "type": "object", "description": "Owner/brand/management replies to the review, each `{id, author, text, published_at}` with `published_at` as an ISO 8601 UTC string (REL-07.6).", "properties": { "id": { "type": [ "string", "null" ], "description": "String at review.responses.id" }, "author": { "type": [ "string", "null" ], "description": "String at review.responses.author" }, "text": { "type": [ "string", "null" ], "description": "String at review.responses.text" }, "published_at": { "type": [ "string", "number", "null" ], "description": "Union: string | number | null" } } } }, "published_at": { "type": [ "string", "number", "null" ], "description": "Review creation timestamp as an ISO 8601 UTC string (REL-07.6). Upstreams that send only a calendar date land on midnight UTC. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `review.ext.published_at_epoch`." }, "ext": { "type": [ "object", "null" ], "description": "Nested object: review.ext", "properties": { "appdata": { "type": [ "object", "null" ], "description": "Object at review.ext.appdata" }, "tiktokshop": { "type": [ "object", "null" ], "description": "Object at review.ext.tiktokshop" }, "naver": { "type": [ "object", "null" ], "description": "Nested object: review.ext.naver", "properties": { "visit_count": { "type": [ "number", "null" ], "description": "Numeric at review.ext.naver.visit_count" }, "verified_by": { "type": [ "string", "null" ], "description": "String at review.ext.naver.verified_by" }, "treatment": { "type": [ "string", "null" ], "description": "String at review.ext.naver.treatment" }, "view_count": { "type": [ "number", "null" ], "description": "Numeric at review.ext.naver.view_count" }, "keywords": { "type": [ "array", "null" ], "description": "Array at review.ext.naver.keywords", "items": { "type": "string", "description": "String at review.ext.naver.keywords" } }, "dedupe_key": { "type": [ "string", "null" ], "description": "String at review.ext.naver.dedupe_key" } } } } } } } } } }, "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 } } } } }, "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": "google", "endpoint": "/v1/google/business/extended-reviews", "data": { "items": [ { "review": { "id": "Ci9DQUlRQUNvZENodHljRjlvT210aVMxWm5aRkZFWVV0M2JYa3pPVU5rVVdJdFJrRRAB", "entity_id": "10008150968882388764", "url": "https://example.com/redacted", "title": null, "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).", "rating": { "value": 4, "max": 5 }, "author": { "name": "user_688a58", "avatar_url": "https://example.com/avatars/user_04ed23.png", "url": "https://example.com/user_918931", "location": null, "reviews_count": 1076 }, "helpful_votes": null, "verified": null, "source": "https://example.com/redacted", "language": null, "original_language": null, "translated": false, "images": [ "https://example.com/redacted", "https://example.com/redacted" ], "responses": null, "published_at": "Sample comment text (redacted)." } }, { "review": { "id": "ChdDSUhNMG9nS0VJQ0FnSUNqN0s3M3BRRRAB", "entity_id": "10008150968882388764", "url": "https://example.com/redacted", "title": null, "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).", "rating": { "value": 5, "max": 5 }, "author": { "name": "user_b21b76", "avatar_url": "https://example.com/avatars/user_54bb04.png", "url": "https://example.com/user_9ebcce", "location": null, "reviews_count": 45 }, "helpful_votes": null, "verified": null, "source": "https://example.com/redacted", "language": null, "original_language": null, "translated": false, "images": [ "https://example.com/redacted", "https://example.com/redacted" ], "responses": null, "published_at": "Sample comment text (redacted)." } } ], "total": 16, "dropped": 0 }, "credits_used": 5, "credits_remaining": 9999, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": null, "has_more": false, "page_size": 16 } } } } }, "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" } } } } } } }, "/google/business/updates": { "get": { "summary": "Get Google Business Profile posts (updates)", "description": "Returns the owner-published posts (updates) on a Google Business Profile: text, image, publish date, and any call-to-action link. Most businesses publish none; an empty result is a valid 'no posts' answer. Identify the business by keyword or cid.", "tags": [ "google" ], "operationId": "get_google_business_updates", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "x-socialcrawl-oneOf": [ [ "keyword", "cid" ] ], "parameters": [ { "name": "keyword", "in": "query", "required": false, "description": "Business name + location (e.g. 'Toyota of Manhattan New York'). (one of: keyword, cid; at least one required)", "schema": { "type": "string" }, "example": "Toyota of Manhattan New York" }, { "name": "cid", "in": "query", "required": false, "description": "Google customer id (cid) of the business. (one of: keyword, cid; at least one required)", "schema": { "type": "string" } }, { "name": "location_name", "in": "query", "required": false, "description": "Geographic context as 'City,Region,Country'.", "schema": { "type": "string" } }, { "name": "language_name", "in": "query", "required": false, "description": "Result language (default 'English').", "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_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": "google" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/google/business/updates" }, "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." }, "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/profile/videos", "data": { "items": [ { "post": { "id": "7658005300657638669", "url": "https://www.tiktok.com/@user_ae6bf3/video/7658005300657638669", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000", "thumbnail_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover", "duration_seconds": 16.903 }, "author": { "username": "user_ae6bf3", "display_name": "user_de35a8", "avatar_url": "https://example.com/avatars/user_3c9283.png", "verified": true }, "engagement": { "views": 3417578, "likes": 501973, "comments": 2618, "shares": 6304, "saves": 22989 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2026-07-02T18:51:58.000Z", "ext": { "music_id": "7656080164593437471", "published_at_epoch": 1783018318 } }, "computed": { "engagement_rate": 0.14949, "language": null, "content_category": "other", "estimated_reach": 4101094 } }, { "post": { "id": "7657606229484670221", "url": "https://www.tiktok.com/@user_ae6bf3/video/7657606229484670221", "content": { "text": "Sample comment text (redacted).", "media_urls": "https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000", "thumbnail_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover", "duration_seconds": 10.123 }, "author": { "username": "user_ae6bf3", "display_name": "user_de35a8", "avatar_url": "https://example.com/avatars/user_3c9283.png", "verified": true }, "engagement": { "views": 7205601, "likes": 739100, "comments": 1943, "shares": 6268, "saves": 28516 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2026-07-01T17:03:22.000Z", "ext": { "music_id": "7656080164593437471", "published_at_epoch": 1782925402 } }, "computed": { "engagement_rate": 0.103713, "language": null, "content_category": "other", "estimated_reach": 8646721 } }, { "post": { "id": "7657287641641143565", "url": "https://www.tiktok.com/@user_ae6bf3/video/7657287641641143565", "content": { "text": null, "media_urls": "https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000", "thumbnail_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover", "duration_seconds": 6.467 }, "author": { "username": "user_ae6bf3", "display_name": "user_de35a8", "avatar_url": "https://example.com/avatars/user_3c9283.png", "verified": true }, "engagement": { "views": 5941789, "likes": 941067, "comments": 3165, "shares": 17173, "saves": 18760 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2026-06-30T20:27:04.000Z", "ext": { "music_id": "7530783142774065975", "published_at_epoch": 1782851224 } }, "computed": { "engagement_rate": 0.161804, "language": null, "content_category": null, "estimated_reach": 7130147 } } ], "next_cursor": "1782516110000", "total": 10, "dropped": 0 }, "credits_used": 1, "credits_remaining": 9999, "request_id": "req-8Kq2ZmR4vT9xLb3P", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0", "has_more": true, "page_size": 10 } } } } }, "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" } } } } } } }, "/google/business/questions": { "get": { "summary": "Get Google Business Profile questions & answers", "description": "Returns the community Q&A on a Google Business Profile: each question and its answers flattened into one comment list linked by parent_id. Identify the business by keyword, cid, or place_id.", "tags": [ "google" ], "operationId": "get_google_business_questions", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "x-socialcrawl-oneOf": [ [ "keyword", "cid", "place_id" ] ], "parameters": [ { "name": "keyword", "in": "query", "required": false, "description": "Business name + location (e.g. 'Starbucks Reserve Roastery New York'). (one of: keyword, cid, place_id; at least one required)", "schema": { "type": "string" }, "example": "Starbucks Reserve Roastery New York" }, { "name": "cid", "in": "query", "required": false, "description": "Google customer id (cid) of the business. (one of: keyword, cid, place_id; at least one required)", "schema": { "type": "string" } }, { "name": "place_id", "in": "query", "required": false, "description": "Google place_id of the business. (one of: keyword, cid, place_id; at least one required)", "schema": { "type": "string" } }, { "name": "location_name", "in": "query", "required": false, "description": "Geographic context as 'City,Region,Country'.", "schema": { "type": "string" } }, { "name": "language_name", "in": "query", "required": false, "description": "Result language (default 'English').", "schema": { "type": "string" } }, { "name": "depth", "in": "query", "required": false, "description": "Number of questions to return (default 20).", "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_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": "google" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/google/business/questions" }, "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." }, "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." } } } } } }, "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" } } } } } } }, "/google/business/search": { "get": { "summary": "Search Google Maps businesses", "description": "Returns the Google Maps businesses for a keyword or category in a place, in Google's own order: name, cid, place_id, address, phone, website, category and additional categories, star rating and review count, coordinates, claimed status and opening hours. `place.id` is the cid, so any row chains into GET /v1/google/business/info?cid= or /v1/google/business/extended-reviews?cid=. `place.ext` adds `place_id`, `maps_url`, `domain`, `rank`, `city`, `postal_code`, `region`, `country_code`, `hours` and `status`. Give the place as `location` (\"Milano, Italy\", a country, or a full \"City,Region,Country\" name such as \"Milan,Lombardy,Italy\") or as `lat` + `lng` (with an optional `zoom`); sending neither, or both, is a free 400. Sponsored listings are left out. A flat 5 credits for up to 100 places; a search with no results returns an empty list and is not billed.", "tags": [ "google" ], "operationId": "get_google_business_search", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "x-socialcrawl-oneOf": [ [ "location", "lat" ] ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "What to look for, as you would type it into Google Maps: a category or trade ('dentista', 'ristorante', 'commercialista') or a business name. Use the local language for local results.", "schema": { "type": "string" }, "example": "dentista" }, { "name": "location", "in": "query", "required": false, "description": "Where to search: 'City, Country' (e.g. 'Milano, Italy'), a country name or ISO code ('Italy', 'IT'), or a full City,Region,Country name ('Milan,Lombardy,Italy'). Required unless lat and lng are sent. (one of: location, lat; at least one required)", "schema": { "type": "string" }, "example": "Milano, Italy" }, { "name": "lat", "in": "query", "required": false, "description": "Latitude of the search centre (-90 to 90). Send with lng instead of location. (one of: location, lat; at least one required)", "schema": { "type": "string" } }, { "name": "lng", "in": "query", "required": false, "description": "Longitude of the search centre (-180 to 180). Send with lat instead of location.", "schema": { "type": "string" } }, { "name": "zoom", "in": "query", "required": false, "description": "Google Maps zoom level around lat/lng, 3 (continent) to 21 (street). Defaults to 14, about a city district. Only with lat/lng.", "schema": { "type": "integer", "minimum": 3, "maximum": 21 } }, { "name": "language", "in": "query", "required": false, "description": "Language code for the results ('it', 'en', 'de'). Defaults to the main language of the country in location ('it' for Italy), or 'en' for coordinates.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many places to return, 1-100 (default 20). The price is the same at any limit.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "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": "google" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/google/business/search" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical place wrappers ({ place })", "items": { "type": "object", "description": "Canonical place wrapper", "properties": { "place": { "type": "object", "description": "Canonical Place object (physical/local business or hotel)", "properties": { "id": { "type": "string", "description": "Place ID (Google cid for a business, hotel_identifier for a hotel)" }, "name": { "type": [ "string", "null" ], "description": "Business / hotel name" }, "url": { "type": [ "string", "null" ], "description": "Website or canonical URL" }, "category": { "type": [ "string", "null" ], "description": "Primary category (e.g. \"Coffee shop\", \"Hotel\")" }, "rating": { "type": "object", "description": "Aggregate rating (value + max)", "properties": { "value": { "type": [ "number", "null" ], "description": "Numeric at place.rating.value" }, "max": { "type": [ "number", "null" ], "description": "Numeric at place.rating.max" } } }, "reviews_count": { "type": [ "number", "null" ], "description": "Number of ratings" }, "price_level": { "type": [ "string", "null" ], "description": "Price band (\"inexpensive\" / \"$$\" / null)" }, "address": { "type": [ "string", "null" ], "description": "String at place.address" }, "phone": { "type": [ "string", "null" ], "description": "String at place.phone" }, "latitude": { "type": [ "number", "null" ], "description": "Numeric at place.latitude" }, "longitude": { "type": [ "number", "null" ], "description": "Numeric at place.longitude" }, "verified": { "type": [ "boolean", "null" ], "description": "Claimed-business flag (Google is_claimed)" }, "description": { "type": [ "string", "null" ], "description": "String at place.description" }, "image_urls": { "type": [ "string", "array", "null" ], "description": "Union: string | array | null", "items": { "type": "string", "description": "String at place.image_urls" } }, "categories": { "type": [ "array", "null" ], "description": "Array at place.categories", "items": { "type": "string", "description": "String at place.categories" } }, "hotel": { "type": [ "object", "null" ], "description": "Hotel-only richness (stars, amenities, review topics, prices); null for plain places", "properties": { "stars": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.stars" }, "stars_description": { "type": [ "string", "null" ], "description": "String at place.hotel.stars_description" }, "check_in_time": { "type": [ "string", "null" ], "description": "String at place.hotel.check_in_time" }, "check_out_time": { "type": [ "string", "null" ], "description": "String at place.hotel.check_out_time" }, "amenities": { "type": [ "array", "null" ], "description": "Array at place.hotel.amenities", "items": { "type": "object", "description": "Nested object: place.hotel.amenities", "properties": { "category": { "type": [ "string", "null" ], "description": "String at place.hotel.amenities.category" }, "name": { "type": [ "string", "null" ], "description": "String at place.hotel.amenities.name" }, "available": { "type": [ "boolean", "null" ], "description": "Boolean at place.hotel.amenities.available" }, "hint": { "type": [ "string", "null" ], "description": "String at place.hotel.amenities.hint" } } } }, "review_topics": { "type": [ "array", "null" ], "description": "Array at place.hotel.review_topics", "items": { "type": "object", "description": "Nested object: place.hotel.review_topics", "properties": { "title": { "type": [ "string", "null" ], "description": "String at place.hotel.review_topics.title" }, "positive_score": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.review_topics.positive_score" }, "positive_count": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.review_topics.positive_count" }, "negative_count": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.review_topics.negative_count" }, "total_count": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.review_topics.total_count" } } } }, "prices": { "type": [ "array", "null" ], "description": "Array at place.hotel.prices", "items": { "type": "object", "description": "Nested object: place.hotel.prices", "properties": { "title": { "type": [ "string", "null" ], "description": "String at place.hotel.prices.title" }, "price": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.prices.price" }, "currency": { "type": [ "string", "null" ], "description": "String at place.hotel.prices.currency" }, "url": { "type": [ "string", "null" ], "description": "String at place.hotel.prices.url" }, "official_site": { "type": [ "boolean", "null" ], "description": "Boolean at place.hotel.prices.official_site" } } } } } }, "ext": { "type": [ "object", "null" ], "description": "Nested object: place.ext", "properties": { "distance": { "type": [ "number", "null" ], "description": "Numeric at place.ext.distance" }, "status": { "type": [ "string", "null" ], "description": "String at place.ext.status" }, "timezone": { "type": [ "string", "null" ], "description": "String at place.ext.timezone" }, "hours": { "type": [ "array", "null" ], "description": "Array at place.ext.hours", "items": { "type": "object", "description": "Nested object: place.ext.hours", "properties": { "date": { "type": [ "string", "null" ], "description": "String at place.ext.hours.date" }, "day_name": { "type": [ "string", "null" ], "description": "String at place.ext.hours.day_name" }, "is_open": { "type": [ "boolean", "null" ], "description": "Boolean at place.ext.hours.is_open" }, "opens_at": { "type": [ "string", "null" ], "description": "String at place.ext.hours.opens_at" }, "closes_at": { "type": [ "string", "null" ], "description": "String at place.ext.hours.closes_at" } } } }, "place_id": { "type": [ "string", "null" ], "description": "String at place.ext.place_id" }, "attributes": { "type": [ "object", "null" ], "description": "Object at place.ext.attributes" }, "rating_distribution": { "type": [ "object", "null" ], "description": "Object at place.ext.rating_distribution", "additionalProperties": { "type": "number", "description": "Numeric at place.ext.rating_distribution.*" } }, "people_also_search": { "type": [ "array", "null" ], "description": "Array at place.ext.people_also_search", "items": { "type": "object", "description": "Nested object: place.ext.people_also_search", "properties": { "cid": { "type": [ "string", "null" ], "description": "String at place.ext.people_also_search.cid" }, "title": { "type": [ "string", "null" ], "description": "String at place.ext.people_also_search.title" }, "rating": { "type": [ "object", "null" ], "description": "Nested object: place.ext.people_also_search.rating", "properties": { "value": { "type": [ "number", "null" ], "description": "Numeric at place.ext.people_also_search.rating.value" }, "votes_count": { "type": [ "number", "null" ], "description": "Numeric at place.ext.people_also_search.rating.votes_count" } } } } } }, "menu_url": { "type": [ "string", "null" ], "description": "String at place.ext.menu_url" }, "domain": { "type": [ "string", "null" ], "description": "String at place.ext.domain" }, "maps_url": { "type": [ "string", "null" ], "description": "String at place.ext.maps_url" }, "rank": { "type": [ "number", "null" ], "description": "Numeric at place.ext.rank" }, "city": { "type": [ "string", "null" ], "description": "String at place.ext.city" }, "postal_code": { "type": [ "string", "null" ], "description": "String at place.ext.postal_code" }, "region": { "type": [ "string", "null" ], "description": "String at place.ext.region" }, "country_code": { "type": [ "string", "null" ], "description": "String at place.ext.country_code" }, "posts_count": { "type": [ "number", "null" ], "description": "`/v1/instagram/location` only: the number of public posts Instagram counts at the place." }, "website": { "type": [ "string", "null" ], "description": "`/v1/instagram/location` only: the venue's own website (`place.url` is its Instagram page)." }, "facebook_places_id": { "type": [ "string", "null" ], "description": "`/v1/instagram/location` only: the Facebook Places id of the same place." }, "business_username": { "type": [ "string", "null" ], "description": "`/v1/instagram/location` only: the username of the Instagram business account linked to the place, or null when none is linked." }, "is_ad": { "type": [ "boolean", "null" ], "description": "Boolean at place.ext.is_ad" }, "ad_rank": { "type": [ "number", "null" ], "description": "Numeric at place.ext.ad_rank" }, "ad_description": { "type": [ "string", "null" ], "description": "String at place.ext.ad_description" }, "status_description": { "type": [ "string", "null" ], "description": "String at place.ext.status_description" }, "visitor_reviews_count": { "type": [ "number", "null" ], "description": "Numeric at place.ext.visitor_reviews_count" }, "blog_reviews_count": { "type": [ "number", "null" ], "description": "Numeric at place.ext.blog_reviews_count" }, "booking_url": { "type": [ "string", "null" ], "description": "String at place.ext.booking_url" }, "keywords": { "type": [ "array", "null" ], "description": "Array at place.ext.keywords", "items": { "type": "string", "description": "String at place.ext.keywords" } } } } } } } } }, "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": "target", "endpoint": "/v1/target/stores", "data": { "items": [ { "place": { "id": "3412", "name": "Chelsea 23rd and 8th", "url": null, "category": null, "rating": { "value": null, "max": null }, "reviews_count": null, "price_level": null, "address": "258 8th Ave, New York, NY 10011-1619", "phone": "646-720-0024", "latitude": null, "longitude": null, "verified": null, "description": null, "image_urls": null, "ext": { "distance": 0.37, "status": "Open", "timezone": "America/New_York", "hours": [ { "date": "2026-09-16", "day_name": "Wednesday", "is_open": true, "opens_at": "08:00:00", "closes_at": "23:00:00" }, { "date": "2026-09-17", "day_name": "Thursday", "is_open": true, "opens_at": "08:00:00", "closes_at": "23:00:00" } ] } } }, { "place": { "id": "3277", "name": "Manhattan Herald Square", "url": null, "category": null, "rating": { "value": null, "max": null }, "reviews_count": null, "price_level": null, "address": "112 W 34th St, New York, NY 10120-0101", "phone": "646-968-4739", "latitude": null, "longitude": null, "verified": null, "description": null, "image_urls": null, "ext": { "distance": 0.42, "status": "Open", "timezone": "America/New_York", "hours": [ { "date": "2026-09-16", "day_name": "Wednesday", "is_open": true, "opens_at": "08:00:00", "closes_at": "23:00:00" }, { "date": "2026-09-17", "day_name": "Thursday", "is_open": true, "opens_at": "08:00:00", "closes_at": "23:00:00" } ] } } } ], "total": 20, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": null, "has_more": false, "page_size": 20 }, "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" } } } } } } }, "/google/hotels/search": { "get": { "summary": "Search Google hotels", "description": "Returns hotels for a query from Google Travel: name, star rating, review score, coordinates, images, and nightly price. Dates default to next-day / one-night / two-visitors when omitted. Each hotel_identifier can be passed to GET /v1/google/hotels/info for full detail.", "tags": [ "google" ], "operationId": "get_google_hotels_search", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "keyword", "in": "query", "required": true, "description": "Hotel search query (e.g. 'hotels in New York').", "schema": { "type": "string" }, "example": "hotels in New York" }, { "name": "location_name", "in": "query", "required": false, "description": "Geographic context as 'City,Region,Country'.", "schema": { "type": "string" } }, { "name": "language_name", "in": "query", "required": false, "description": "Result language (default 'English').", "schema": { "type": "string" } }, { "name": "check_in", "in": "query", "required": false, "description": "Check-in date (YYYY-MM-DD). Defaults to the next day.", "schema": { "type": "string" } }, { "name": "check_out", "in": "query", "required": false, "description": "Check-out date (YYYY-MM-DD). Defaults to one night.", "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": "google" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/google/hotels/search" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical place wrappers ({ place })", "items": { "type": "object", "description": "Canonical place wrapper", "properties": { "place": { "type": "object", "description": "Canonical Place object (physical/local business or hotel)", "properties": { "id": { "type": "string", "description": "Place ID (Google cid for a business, hotel_identifier for a hotel)" }, "name": { "type": [ "string", "null" ], "description": "Business / hotel name" }, "url": { "type": [ "string", "null" ], "description": "Website or canonical URL" }, "category": { "type": [ "string", "null" ], "description": "Primary category (e.g. \"Coffee shop\", \"Hotel\")" }, "rating": { "type": "object", "description": "Aggregate rating (value + max)", "properties": { "value": { "type": [ "number", "null" ], "description": "Numeric at place.rating.value" }, "max": { "type": [ "number", "null" ], "description": "Numeric at place.rating.max" } } }, "reviews_count": { "type": [ "number", "null" ], "description": "Number of ratings" }, "price_level": { "type": [ "string", "null" ], "description": "Price band (\"inexpensive\" / \"$$\" / null)" }, "address": { "type": [ "string", "null" ], "description": "String at place.address" }, "phone": { "type": [ "string", "null" ], "description": "String at place.phone" }, "latitude": { "type": [ "number", "null" ], "description": "Numeric at place.latitude" }, "longitude": { "type": [ "number", "null" ], "description": "Numeric at place.longitude" }, "verified": { "type": [ "boolean", "null" ], "description": "Claimed-business flag (Google is_claimed)" }, "description": { "type": [ "string", "null" ], "description": "String at place.description" }, "image_urls": { "type": [ "string", "array", "null" ], "description": "Union: string | array | null", "items": { "type": "string", "description": "String at place.image_urls" } }, "categories": { "type": [ "array", "null" ], "description": "Array at place.categories", "items": { "type": "string", "description": "String at place.categories" } }, "hotel": { "type": [ "object", "null" ], "description": "Hotel-only richness (stars, amenities, review topics, prices); null for plain places", "properties": { "stars": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.stars" }, "stars_description": { "type": [ "string", "null" ], "description": "String at place.hotel.stars_description" }, "check_in_time": { "type": [ "string", "null" ], "description": "String at place.hotel.check_in_time" }, "check_out_time": { "type": [ "string", "null" ], "description": "String at place.hotel.check_out_time" }, "amenities": { "type": [ "array", "null" ], "description": "Array at place.hotel.amenities", "items": { "type": "object", "description": "Nested object: place.hotel.amenities", "properties": { "category": { "type": [ "string", "null" ], "description": "String at place.hotel.amenities.category" }, "name": { "type": [ "string", "null" ], "description": "String at place.hotel.amenities.name" }, "available": { "type": [ "boolean", "null" ], "description": "Boolean at place.hotel.amenities.available" }, "hint": { "type": [ "string", "null" ], "description": "String at place.hotel.amenities.hint" } } } }, "review_topics": { "type": [ "array", "null" ], "description": "Array at place.hotel.review_topics", "items": { "type": "object", "description": "Nested object: place.hotel.review_topics", "properties": { "title": { "type": [ "string", "null" ], "description": "String at place.hotel.review_topics.title" }, "positive_score": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.review_topics.positive_score" }, "positive_count": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.review_topics.positive_count" }, "negative_count": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.review_topics.negative_count" }, "total_count": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.review_topics.total_count" } } } }, "prices": { "type": [ "array", "null" ], "description": "Array at place.hotel.prices", "items": { "type": "object", "description": "Nested object: place.hotel.prices", "properties": { "title": { "type": [ "string", "null" ], "description": "String at place.hotel.prices.title" }, "price": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.prices.price" }, "currency": { "type": [ "string", "null" ], "description": "String at place.hotel.prices.currency" }, "url": { "type": [ "string", "null" ], "description": "String at place.hotel.prices.url" }, "official_site": { "type": [ "boolean", "null" ], "description": "Boolean at place.hotel.prices.official_site" } } } } } }, "ext": { "type": [ "object", "null" ], "description": "Nested object: place.ext", "properties": { "distance": { "type": [ "number", "null" ], "description": "Numeric at place.ext.distance" }, "status": { "type": [ "string", "null" ], "description": "String at place.ext.status" }, "timezone": { "type": [ "string", "null" ], "description": "String at place.ext.timezone" }, "hours": { "type": [ "array", "null" ], "description": "Array at place.ext.hours", "items": { "type": "object", "description": "Nested object: place.ext.hours", "properties": { "date": { "type": [ "string", "null" ], "description": "String at place.ext.hours.date" }, "day_name": { "type": [ "string", "null" ], "description": "String at place.ext.hours.day_name" }, "is_open": { "type": [ "boolean", "null" ], "description": "Boolean at place.ext.hours.is_open" }, "opens_at": { "type": [ "string", "null" ], "description": "String at place.ext.hours.opens_at" }, "closes_at": { "type": [ "string", "null" ], "description": "String at place.ext.hours.closes_at" } } } }, "place_id": { "type": [ "string", "null" ], "description": "String at place.ext.place_id" }, "attributes": { "type": [ "object", "null" ], "description": "Object at place.ext.attributes" }, "rating_distribution": { "type": [ "object", "null" ], "description": "Object at place.ext.rating_distribution", "additionalProperties": { "type": "number", "description": "Numeric at place.ext.rating_distribution.*" } }, "people_also_search": { "type": [ "array", "null" ], "description": "Array at place.ext.people_also_search", "items": { "type": "object", "description": "Nested object: place.ext.people_also_search", "properties": { "cid": { "type": [ "string", "null" ], "description": "String at place.ext.people_also_search.cid" }, "title": { "type": [ "string", "null" ], "description": "String at place.ext.people_also_search.title" }, "rating": { "type": [ "object", "null" ], "description": "Nested object: place.ext.people_also_search.rating", "properties": { "value": { "type": [ "number", "null" ], "description": "Numeric at place.ext.people_also_search.rating.value" }, "votes_count": { "type": [ "number", "null" ], "description": "Numeric at place.ext.people_also_search.rating.votes_count" } } } } } }, "menu_url": { "type": [ "string", "null" ], "description": "String at place.ext.menu_url" }, "domain": { "type": [ "string", "null" ], "description": "String at place.ext.domain" }, "maps_url": { "type": [ "string", "null" ], "description": "String at place.ext.maps_url" }, "rank": { "type": [ "number", "null" ], "description": "Numeric at place.ext.rank" }, "city": { "type": [ "string", "null" ], "description": "String at place.ext.city" }, "postal_code": { "type": [ "string", "null" ], "description": "String at place.ext.postal_code" }, "region": { "type": [ "string", "null" ], "description": "String at place.ext.region" }, "country_code": { "type": [ "string", "null" ], "description": "String at place.ext.country_code" }, "posts_count": { "type": [ "number", "null" ], "description": "`/v1/instagram/location` only: the number of public posts Instagram counts at the place." }, "website": { "type": [ "string", "null" ], "description": "`/v1/instagram/location` only: the venue's own website (`place.url` is its Instagram page)." }, "facebook_places_id": { "type": [ "string", "null" ], "description": "`/v1/instagram/location` only: the Facebook Places id of the same place." }, "business_username": { "type": [ "string", "null" ], "description": "`/v1/instagram/location` only: the username of the Instagram business account linked to the place, or null when none is linked." }, "is_ad": { "type": [ "boolean", "null" ], "description": "Boolean at place.ext.is_ad" }, "ad_rank": { "type": [ "number", "null" ], "description": "Numeric at place.ext.ad_rank" }, "ad_description": { "type": [ "string", "null" ], "description": "String at place.ext.ad_description" }, "status_description": { "type": [ "string", "null" ], "description": "String at place.ext.status_description" }, "visitor_reviews_count": { "type": [ "number", "null" ], "description": "Numeric at place.ext.visitor_reviews_count" }, "blog_reviews_count": { "type": [ "number", "null" ], "description": "Numeric at place.ext.blog_reviews_count" }, "booking_url": { "type": [ "string", "null" ], "description": "String at place.ext.booking_url" }, "keywords": { "type": [ "array", "null" ], "description": "Array at place.ext.keywords", "items": { "type": "string", "description": "String at place.ext.keywords" } } } } } } } } }, "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": "google", "endpoint": "/v1/google/hotels/search", "data": { "items": [ { "place": { "id": "ChoIxPKIzoX4zIfLARoNL2cvMTFwd2g1N2c1NRAB", "name": "31 Street Broadway Hotel", "url": null, "category": "Hotel", "rating": { "value": 2.6, "max": 5 }, "reviews_count": 439, "price_level": null, "address": null, "phone": null, "latitude": 40.747211, "longitude": -73.9878074, "verified": null, "description": null, "image_urls": [ "https://lh3.googleusercontent.com/gps-cs-s/AHRPTWmOW8SBhbFljBfsPnlLfB4Quy-xJqqBv_T8HONDh3vkHu3lGiOCGZecVO6EQH0TqK1WsJ5HrwY8JSuC9E6JQtf1xFzN86tYFQ4imBM7pbfr8xiKUi6ZSY0a_019tbahriNXgDuDLlTB6do=s287-w287-h192-n-k-no-v1", "https://lh3.googleusercontent.com/gps-cs-s/AHRPTWmrwcoHgKzq2j-6yxz6gtnstCH1XAYmoxkwETqGBj5NEeckpGWo9GXpaxKwK7a5nfUkCBDzkFyYhcYh41R9aA1p381haWZXvMXqtBGF1g-gBdgycjgdGQq3iE2rSLLMlPsYf_q3MdCYh5o=s287-w287-h192-n-k-no-v1" ], "hotel": { "stars": 3, "stars_description": null, "check_in_time": null, "check_out_time": null, "amenities": null, "review_topics": null, "prices": null } } }, { "place": { "id": "ChkIkPCX3P7fgYq2ARoML2cvMTF5OXpjcWdzEAE", "name": "Hotel Executive Suites", "url": null, "category": "Hotel", "rating": { "value": 3.4, "max": 5 }, "reviews_count": 1347, "price_level": null, "address": null, "phone": null, "latitude": 40.5906024, "longitude": -74.2388923, "verified": null, "description": null, "image_urls": [ "https://lh5.googleusercontent.com/proxy/_IGCGNLsJDrnAYuCJx5XiSbRU0TOnECDZzC063xyBF7oMrjcVldSqUrhd2lEn0AkNuySLE0ze3Bx6bof8PH-Udnxd5JwdfgbQcOl20-HmuaoBirAVydxbTU2tkhlPsfxFI8iRMoKH3y0HV1dlM9amOXckcU3uU33wmndakFapQ=s287-w287-h192-n-k-no-v1", "https://lh3.googleusercontent.com/gps-cs-s/AHRPTWnsjwqAuNgWyA6yOHXyYI19o11j1OgFNlmYhVl1hMdGMv4DAZ_-W-ZoX3G0-nwwBuq5FAhCxV0imGYsSEPm9gJT6yDkLul2ooSVv9xzfP7mlWZHfmiWdC6vpeqOnAcqDBQfU44N=s287-w287-h192-n-k-no-v1" ], "hotel": { "stars": 3, "stars_description": null, "check_in_time": null, "check_out_time": null, "amenities": null, "review_topics": null, "prices": null } } } ], "total": 20, "dropped": 0 }, "credits_used": 1, "credits_remaining": 9999, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": null, "has_more": false, "page_size": 20 } } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/google/hotels/info": { "get": { "summary": "Get Google hotel detail", "description": "Returns full detail for a hotel by its hotel_identifier (from GET /v1/google/hotels/search): description, star rating, address, phone, coordinates, amenities across 14 categories, 27 review-sentiment topics, and a multi-vendor price comparison.", "tags": [ "google" ], "operationId": "get_google_hotels_info", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "advanced", "x-credit-cost": 5, "parameters": [ { "name": "hotel_identifier", "in": "query", "required": true, "description": "Opaque hotel id returned by GET /v1/google/hotels/search.", "schema": { "type": "string" }, "example": "ChkIoYjXwK-S_okHGg0vZy8xMW1fd3MzY243EAE" }, { "name": "location_name", "in": "query", "required": false, "description": "Geographic context as 'City,Region,Country'.", "schema": { "type": "string" } }, { "name": "language_name", "in": "query", "required": false, "description": "Result language (default 'English').", "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": "google" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/google/hotels/info" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "place": { "type": "object", "description": "Canonical Place object (physical/local business or hotel)", "properties": { "id": { "type": "string", "description": "Place ID (Google cid for a business, hotel_identifier for a hotel)" }, "name": { "type": [ "string", "null" ], "description": "Business / hotel name" }, "url": { "type": [ "string", "null" ], "description": "Website or canonical URL" }, "category": { "type": [ "string", "null" ], "description": "Primary category (e.g. \"Coffee shop\", \"Hotel\")" }, "rating": { "type": "object", "description": "Aggregate rating (value + max)", "properties": { "value": { "type": [ "number", "null" ], "description": "Numeric at place.rating.value" }, "max": { "type": [ "number", "null" ], "description": "Numeric at place.rating.max" } } }, "reviews_count": { "type": [ "number", "null" ], "description": "Number of ratings" }, "price_level": { "type": [ "string", "null" ], "description": "Price band (\"inexpensive\" / \"$$\" / null)" }, "address": { "type": [ "string", "null" ], "description": "String at place.address" }, "phone": { "type": [ "string", "null" ], "description": "String at place.phone" }, "latitude": { "type": [ "number", "null" ], "description": "Numeric at place.latitude" }, "longitude": { "type": [ "number", "null" ], "description": "Numeric at place.longitude" }, "verified": { "type": [ "boolean", "null" ], "description": "Claimed-business flag (Google is_claimed)" }, "description": { "type": [ "string", "null" ], "description": "String at place.description" }, "image_urls": { "type": [ "string", "array", "null" ], "description": "Union: string | array | null", "items": { "type": "string", "description": "String at place.image_urls" } }, "categories": { "type": [ "array", "null" ], "description": "Array at place.categories", "items": { "type": "string", "description": "String at place.categories" } }, "hotel": { "type": [ "object", "null" ], "description": "Hotel-only richness (stars, amenities, review topics, prices); null for plain places", "properties": { "stars": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.stars" }, "stars_description": { "type": [ "string", "null" ], "description": "String at place.hotel.stars_description" }, "check_in_time": { "type": [ "string", "null" ], "description": "String at place.hotel.check_in_time" }, "check_out_time": { "type": [ "string", "null" ], "description": "String at place.hotel.check_out_time" }, "amenities": { "type": [ "array", "null" ], "description": "Array at place.hotel.amenities", "items": { "type": "object", "description": "Nested object: place.hotel.amenities", "properties": { "category": { "type": [ "string", "null" ], "description": "String at place.hotel.amenities.category" }, "name": { "type": [ "string", "null" ], "description": "String at place.hotel.amenities.name" }, "available": { "type": [ "boolean", "null" ], "description": "Boolean at place.hotel.amenities.available" }, "hint": { "type": [ "string", "null" ], "description": "String at place.hotel.amenities.hint" } } } }, "review_topics": { "type": [ "array", "null" ], "description": "Array at place.hotel.review_topics", "items": { "type": "object", "description": "Nested object: place.hotel.review_topics", "properties": { "title": { "type": [ "string", "null" ], "description": "String at place.hotel.review_topics.title" }, "positive_score": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.review_topics.positive_score" }, "positive_count": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.review_topics.positive_count" }, "negative_count": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.review_topics.negative_count" }, "total_count": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.review_topics.total_count" } } } }, "prices": { "type": [ "array", "null" ], "description": "Array at place.hotel.prices", "items": { "type": "object", "description": "Nested object: place.hotel.prices", "properties": { "title": { "type": [ "string", "null" ], "description": "String at place.hotel.prices.title" }, "price": { "type": [ "number", "null" ], "description": "Numeric at place.hotel.prices.price" }, "currency": { "type": [ "string", "null" ], "description": "String at place.hotel.prices.currency" }, "url": { "type": [ "string", "null" ], "description": "String at place.hotel.prices.url" }, "official_site": { "type": [ "boolean", "null" ], "description": "Boolean at place.hotel.prices.official_site" } } } } } }, "ext": { "type": [ "object", "null" ], "description": "Nested object: place.ext", "properties": { "distance": { "type": [ "number", "null" ], "description": "Numeric at place.ext.distance" }, "status": { "type": [ "string", "null" ], "description": "String at place.ext.status" }, "timezone": { "type": [ "string", "null" ], "description": "String at place.ext.timezone" }, "hours": { "type": [ "array", "null" ], "description": "Array at place.ext.hours", "items": { "type": "object", "description": "Nested object: place.ext.hours", "properties": { "date": { "type": [ "string", "null" ], "description": "String at place.ext.hours.date" }, "day_name": { "type": [ "string", "null" ], "description": "String at place.ext.hours.day_name" }, "is_open": { "type": [ "boolean", "null" ], "description": "Boolean at place.ext.hours.is_open" }, "opens_at": { "type": [ "string", "null" ], "description": "String at place.ext.hours.opens_at" }, "closes_at": { "type": [ "string", "null" ], "description": "String at place.ext.hours.closes_at" } } } }, "place_id": { "type": [ "string", "null" ], "description": "String at place.ext.place_id" }, "attributes": { "type": [ "object", "null" ], "description": "Object at place.ext.attributes" }, "rating_distribution": { "type": [ "object", "null" ], "description": "Object at place.ext.rating_distribution", "additionalProperties": { "type": "number", "description": "Numeric at place.ext.rating_distribution.*" } }, "people_also_search": { "type": [ "array", "null" ], "description": "Array at place.ext.people_also_search", "items": { "type": "object", "description": "Nested object: place.ext.people_also_search", "properties": { "cid": { "type": [ "string", "null" ], "description": "String at place.ext.people_also_search.cid" }, "title": { "type": [ "string", "null" ], "description": "String at place.ext.people_also_search.title" }, "rating": { "type": [ "object", "null" ], "description": "Nested object: place.ext.people_also_search.rating", "properties": { "value": { "type": [ "number", "null" ], "description": "Numeric at place.ext.people_also_search.rating.value" }, "votes_count": { "type": [ "number", "null" ], "description": "Numeric at place.ext.people_also_search.rating.votes_count" } } } } } }, "menu_url": { "type": [ "string", "null" ], "description": "String at place.ext.menu_url" }, "domain": { "type": [ "string", "null" ], "description": "String at place.ext.domain" }, "maps_url": { "type": [ "string", "null" ], "description": "String at place.ext.maps_url" }, "rank": { "type": [ "number", "null" ], "description": "Numeric at place.ext.rank" }, "city": { "type": [ "string", "null" ], "description": "String at place.ext.city" }, "postal_code": { "type": [ "string", "null" ], "description": "String at place.ext.postal_code" }, "region": { "type": [ "string", "null" ], "description": "String at place.ext.region" }, "country_code": { "type": [ "string", "null" ], "description": "String at place.ext.country_code" }, "posts_count": { "type": [ "number", "null" ], "description": "`/v1/instagram/location` only: the number of public posts Instagram counts at the place." }, "website": { "type": [ "string", "null" ], "description": "`/v1/instagram/location` only: the venue's own website (`place.url` is its Instagram page)." }, "facebook_places_id": { "type": [ "string", "null" ], "description": "`/v1/instagram/location` only: the Facebook Places id of the same place." }, "business_username": { "type": [ "string", "null" ], "description": "`/v1/instagram/location` only: the username of the Instagram business account linked to the place, or null when none is linked." }, "is_ad": { "type": [ "boolean", "null" ], "description": "Boolean at place.ext.is_ad" }, "ad_rank": { "type": [ "number", "null" ], "description": "Numeric at place.ext.ad_rank" }, "ad_description": { "type": [ "string", "null" ], "description": "String at place.ext.ad_description" }, "status_description": { "type": [ "string", "null" ], "description": "String at place.ext.status_description" }, "visitor_reviews_count": { "type": [ "number", "null" ], "description": "Numeric at place.ext.visitor_reviews_count" }, "blog_reviews_count": { "type": [ "number", "null" ], "description": "Numeric at place.ext.blog_reviews_count" }, "booking_url": { "type": [ "string", "null" ], "description": "String at place.ext.booking_url" }, "keywords": { "type": [ "array", "null" ], "description": "Array at place.ext.keywords", "items": { "type": "string", "description": "String at place.ext.keywords" } } } } } }, "_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": [ "place" ] }, "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": "google", "endpoint": "/v1/google/hotels/info", "data": { "place": { "id": "ChkIoYjXwK-S_okHGg0vZy8xMW1fd3MzY243EAE", "name": "Hotel Riu Plaza Manhattan Times Square", "url": "https://www.riu.com/en/hotel/united-states/new-york/hotel-riu-plaza-manhattan-times-square?utm_source=google&utm_medium=organic&utm_campaign=my_business&utm_content=ZMH", "category": "Hotel", "rating": { "value": 4.7, "max": 5 }, "reviews_count": 9001, "price_level": null, "address": "145 W 47th St, New York, NY 10036", "phone": "+12127063170", "latitude": 40.7589022, "longitude": -73.9836073, "verified": null, "description": "Chic hotel with a fitness room & a theater-inspired dining area, plus breakfast & limited parking.", "image_urls": [ "https://lh3.googleusercontent.com/gps-cs-s/AHRPTWnmV9oPLsNNG-oSpmO1O9evO0qQZhyfxIW-_wacxC183Yz7UnFJmeqC8t1aEAl80DQi21j1vj2fxu_eIirrK4dy34bxfz712Di28GHvSm99bQRZLi0j0d1hCH4POMkvQJL2m_tdBw=s287-w287-h192-n-k-no-v1", "https://lh3.googleusercontent.com/gps-cs-s/AHRPTWk90eNmooNOp5KlLPOrLFkCntHwQ2_IDxv10X_g1h4O4WIIVTo6IspjSMEkZrply7-VUHzj7_Uh85wnzXjQYEMgaHvJrt6fYFriUODvEOdny6njFJe7kfXtfU09crz01DL2BuUq2Q=s287-w287-h192-n-k-no-v1" ], "hotel": { "stars": 4, "stars_description": "4-star hotel", "check_in_time": "15:00", "check_out_time": "12:00", "amenities": [ { "category": "internet", "name": "Wi-Fi", "available": true, "hint": "Free" }, { "category": "internet", "name": "Wi-Fi in public areas", "available": true, "hint": null } ], "review_topics": [ { "title": "Breakfast", "positive_score": 0.42392334, "positive_count": 455, "negative_count": 122, "total_count": 638 }, { "title": "Location", "positive_score": 0.75342035, "positive_count": 976, "negative_count": 27, "total_count": 1059 } ], "prices": null } } }, "credits_used": 5, "credits_remaining": 9999, "request_id": "req_example000000", "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" } } } } } } }, "/google/keyword-volume": { "get": { "summary": "Get Google keyword search volume by country", "description": "Returns Google monthly search volume, cost per click, competition, and a 12-month trend for up to 20 keywords in one country. Response is `{ location, location_name, language, items }`: each item carries `keyword`, `search_volume` (average monthly searches), `cpc` with its `currency`, `competition` (0 to 1) with `competition_level`, `monthly_searches` (the last 12 months, oldest first, as `{ year, month, search_volume }`) and, where Google classifies it, `search_intent`. Use it to compare demand for a product across markets: call it once per country with the same keywords. You get one item per keyword you asked for, in your order. A keyword Google holds no volume for comes back with `search_volume: null`, never 0, so a null means unknown and a 0 means Google reports none. Every null row says why in `null_reason`: `\"withheld\"` means Google stopped publishing volume for the term (since December 2023 it withholds many health and other sensitive terms, such as \"shingles\" or \"herniated disc\"), and such a row carries `last_reported` (`{ year, month, search_volume }`, the last month Google published a figure) with an empty `monthly_searches`; `\"no_data\"` means Google holds no figure at all (very rare or unknown terms). For relative interest in a withheld term, use `/v1/google_trends/explore`, or `/v1/naver/search-trend` in Korea. When no keyword has current volume the call returns 404 and costs 0 credits; its message lists the last published figures. Volumes are Google's own rounded monthly averages and are refreshed monthly, so results are cached for 24 hours. Typical latency is 2 seconds. Priced at a flat 16 credits per call whatever the keyword count, so send all 20 at once.", "tags": [ "google" ], "operationId": "get_google_keyword_volume", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "premium", "x-credit-cost": 16, "parameters": [ { "name": "keywords", "in": "query", "required": true, "description": "1-20 comma-separated keywords (e.g. 'lip gloss,lip oil'). Each keyword may be up to 80 characters. Duplicates are ignored. More than 20 keywords, or a keyword over 80 characters, is rejected with a free 400 before the request is billed.", "schema": { "type": "string" }, "example": "lip gloss,lip oil" }, { "name": "location", "in": "query", "required": false, "description": "Country as an ISO code ('US', 'GB', 'KR'), a full country name ('United Kingdom', 'South Korea') or a numeric location code ('2826'). Defaults to the United States. Volume is published for 94 countries; any other location is rejected with a free 400 naming the accepted forms.", "schema": { "type": "string" }, "example": "GB" }, { "name": "language", "in": "query", "required": false, "description": "Language code ('en', 'de', 'ko') the keywords are searched in. Defaults to the first language listed for the country: Germany is 'de' and Belgium is 'fr', but Vietnam, Indonesia, India, Malaysia, Pakistan, the Philippines, Hong Kong and Singapore default to 'en', so pass their local language (e.g. 'vi', 'id', 'hi') explicitly. A language the country does not hold (Germany in English) is rejected with a free 400 listing the ones it does.", "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 86400 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": 86400 } }, { "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": "google" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/google/keyword-volume" }, "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": "google", "endpoint": "/v1/google/keyword-volume", "data": { "location": "US", "location_name": "United States", "language": "en", "items": [ { "keyword": "hyperhidrosis", "search_volume": 110000, "cpc": 11.73, "currency": "USD", "competition": 0.21, "competition_level": "LOW", "monthly_searches": [ { "year": 2025, "month": 9, "search_volume": 135000 }, { "year": 2025, "month": 10, "search_volume": 135000 }, { "year": 2025, "month": 11, "search_volume": 110000 }, { "year": 2025, "month": 12, "search_volume": 110000 }, { "year": 2026, "month": 1, "search_volume": 110000 }, { "year": 2026, "month": 2, "search_volume": 110000 }, { "year": 2026, "month": 3, "search_volume": 110000 }, { "year": 2026, "month": 4, "search_volume": 110000 }, { "year": 2026, "month": 5, "search_volume": 110000 }, { "year": 2026, "month": 6, "search_volume": 110000 }, { "year": 2026, "month": 7, "search_volume": 110000 }, { "year": 2026, "month": 8, "search_volume": 135000 } ], "search_intent": "informational" }, { "keyword": "shingles", "search_volume": null, "cpc": null, "currency": "USD", "competition": null, "competition_level": null, "monthly_searches": [], "search_intent": "informational", "null_reason": "withheld", "last_reported": { "year": 2023, "month": 11, "search_volume": 673000 } }, { "keyword": "herniated disc", "search_volume": null, "cpc": null, "currency": "USD", "competition": null, "competition_level": null, "monthly_searches": [], "search_intent": "informational", "null_reason": "withheld", "last_reported": { "year": 2023, "month": 12, "search_volume": 165000 } } ], "dropped": 0 }, "credits_used": 16, "credits_remaining": 100, "request_id": "req-AkyBmdWENDrwA50W", "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" }