{ "openapi": "3.1.0", "info": { "title": "SocialCrawl API: Snapchat", "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 Snapchat endpoints only (2 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": "snapchat", "description": "Snapchat endpoints" } ], "paths": { "/snapchat/profile": { "get": { "summary": "Get Snapchat user profile", "description": "Returns public profile information for a Snapchat user including display name, Bitmoji avatar URL, subscriber count, and bio description.", "tags": [ "snapchat" ], "operationId": "get_snapchat_profile", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Snapchat username", "schema": { "type": "string" }, "example": "djkhaled305" }, { "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": "snapchat" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/snapchat/profile" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "author": { "type": "object", "description": "Canonical Author object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)" }, "username": { "type": [ "string", "null" ], "description": "User handle or username" }, "display_name": { "type": [ "string", "null" ], "description": "Display name or full name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to profile picture" }, "bio": { "type": [ "string", "null" ], "description": "Profile biography or description" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the account is verified" }, "followers": { "type": [ "number", "null" ], "description": "Follower or subscriber count as an integer. Exact on Instagram and on TikTok when the source exposes an unrounded figure. YouTube above 1,000 subscribers is YouTube's published three-significant-figure figure. When the integer is a published/rounded value, `author.ext.followers_approximate` is true." }, "following": { "type": [ "number", "null" ], "description": "Number of accounts followed" }, "posts_count": { "type": [ "number", "null" ], "description": "Total number of posts / videos / tracks / episodes" }, "likes_count": { "type": [ "number", "null" ], "description": "Total likes received across the author's content (when surfaced)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the profile page" }, "location": { "type": [ "string", "null" ], "description": "ISO region code (e.g. `US`) or freeform location string when surfaced" }, "external_url": { "type": [ "string", "null" ], "description": "Bio link / external website URL when surfaced by the platform" }, "private": { "type": [ "boolean", "null" ], "description": "Boolean at author.private" }, "joined_at": { "type": [ "string", "null" ], "description": "String at author.joined_at" }, "last_post_at": { "type": [ "string", "null" ], "description": "String at author.last_post_at" }, "ext": { "type": [ "object", "null" ], "description": "Nested object: author.ext", "properties": { "social_context": { "type": [ "string", "null" ], "description": "String at author.ext.social_context" }, "account_created": { "type": [ "string", "null" ], "description": "String at author.ext.account_created" }, "country": { "type": [ "string", "null" ], "description": "String at author.ext.country" }, "country_name": { "type": [ "string", "null" ], "description": "String at author.ext.country_name" }, "collects_received": { "type": [ "number", "null" ], "description": "Numeric at author.ext.collects_received" }, "former_usernames": { "type": [ "array", "null" ], "description": "Array at author.ext.former_usernames", "items": { "type": "string", "description": "String at author.ext.former_usernames" } }, "former_usernames_count": { "type": [ "integer", "null" ], "description": "Instagram profile/about: how many former usernames Instagram's \"About this account\" panel lists for the account. 0 when the panel lists none, null when the panel could not be read on this call (the response then carries a note saying so). A count above 0 means the handle was renamed at least once; the names themselves are not published." }, "verified_at": { "type": [ "string", "null" ], "description": "Instagram profile/about, opt-in (`include=verified_at`): the month Instagram verified the account, as the panel shows it (\"April 2024\"). A month, not a date. Null when the account is not verified or the panel shows no verification date. Absent unless requested." }, "public_email": { "type": [ "string", "null" ], "description": "String at author.ext.public_email" }, "contact_email": { "type": [ "string", "null" ], "description": "Opt-in (`contact_email=1` on instagram/profile, youtube/channel and youtube/channel/about). When the bio lists two or more email addresses, the one the creator gives for contacting them personally, copied verbatim. Null when there is one address or none, when every address belongs to a manager, agency or brand, or when the choice was not confident. `author.ext.public_email` (the first address in the bio) is unchanged." }, "public_phone": { "type": [ "string", "null" ], "description": "String at author.ext.public_phone" }, "similar_source": { "type": [ "string", "null" ], "description": "String at author.ext.similar_source" }, "instagram_username": { "type": [ "string", "null" ], "description": "String at author.ext.instagram_username" }, "similar_via": { "type": [ "string", "null" ], "description": "String at author.ext.similar_via" }, "business_category": { "type": [ "string", "null" ], "description": "String at author.ext.business_category" }, "bio_links": { "type": [ "array", "null" ], "description": "Array at author.ext.bio_links", "items": { "type": "object", "description": "Nested object: author.ext.bio_links", "properties": { "title": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.title" }, "url": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.url" }, "link_type": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.link_type" } } } }, "is_business": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_business" }, "is_professional": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_professional" }, "creator_marketplace": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.creator_marketplace" }, "verification_label": { "type": [ "string", "null" ], "description": "String at author.ext.verification_label" }, "fbid": { "type": [ "string", "null" ], "description": "String at author.ext.fbid" }, "hd_avatar_url": { "type": [ "string", "null" ], "description": "String at author.ext.hd_avatar_url" }, "website": { "type": [ "string", "null" ], "description": "String at author.ext.website" }, "cover_url": { "type": [ "string", "null" ], "description": "String at author.ext.cover_url" }, "page_active": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.page_active" }, "employee_count": { "type": [ "number", "null" ], "description": "Numeric at author.ext.employee_count" }, "employee_count_range": { "type": [ "object", "null" ], "description": "Nested object: author.ext.employee_count_range", "properties": { "start": { "type": [ "number", "null" ], "description": "Numeric at author.ext.employee_count_range.start" }, "end": { "type": [ "number", "null" ], "description": "Numeric at author.ext.employee_count_range.end" } } }, "founded_year": { "type": [ "number", "null" ], "description": "Numeric at author.ext.founded_year" }, "company_type": { "type": [ "string", "null" ], "description": "String at author.ext.company_type" }, "tagline": { "type": [ "string", "null" ], "description": "String at author.ext.tagline" }, "specialities": { "type": [ "array", "null" ], "description": "Array at author.ext.specialities", "items": { "type": "string", "description": "String at author.ext.specialities" } }, "industries": { "type": [ "array", "null" ], "description": "Array at author.ext.industries", "items": { "type": "string", "description": "String at author.ext.industries" } }, "headquarters": { "type": [ "object", "null" ], "description": "Object at author.ext.headquarters" }, "locations": { "type": [ "array", "null" ], "description": "Array at author.ext.locations", "items": { "description": "Leaf at author.ext.locations" } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at author.ext.hashtags", "items": { "description": "Leaf at author.ext.hashtags" } }, "funding": { "type": [ "object", "null" ], "description": "Object at author.ext.funding" }, "address": { "type": [ "string", "null" ], "description": "String at author.ext.address" }, "price_range": { "type": [ "string", "null" ], "description": "String at author.ext.price_range" }, "rating": { "type": [ "string", "null" ], "description": "String at author.ext.rating" }, "rating_count": { "type": [ "number", "null" ], "description": "Numeric at author.ext.rating_count" }, "talking_about_count": { "type": [ "number", "null" ], "description": "Numeric at author.ext.talking_about_count" }, "business_hours": { "type": [ "array", "null" ], "description": "Array at author.ext.business_hours", "items": { "description": "Leaf at author.ext.business_hours" } }, "links": { "type": [ "array", "null" ], "description": "Array at author.ext.links", "items": { "description": "Leaf at author.ext.links" } }, "ad_library_page_id": { "type": [ "string", "null" ], "description": "String at author.ext.ad_library_page_id" }, "ad_library_status": { "type": [ "string", "null" ], "description": "String at author.ext.ad_library_status" }, "urn": { "type": [ "string", "null" ], "description": "String at author.ext.urn" }, "is_top_voice": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_top_voice" }, "is_premium": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_premium" }, "is_creator": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_creator" }, "is_influencer": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_influencer" }, "is_open_to_work": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_open_to_work" }, "is_hiring": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_hiring" }, "member_id": { "type": [ "string", "null" ], "description": "String at author.ext.member_id" }, "company_id": { "type": [ "string", "null" ], "description": "String at author.ext.company_id" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at author.ext.reaction_type" }, "followers_approximate": { "type": [ "boolean", "null" ], "description": "True when `author.followers` is a published or rounded figure rather than an unrounded census: LinkedIn people-list display buckets, TikTok `stats.followerCount` when the exact sibling is absent, and YouTube subscriber counts at or above 1,000. Null or absent on exact counts." }, "counts_source": { "type": [ "string", "null" ], "enum": [ "app", "web", null ], "description": "TikTok profile only. Which of TikTok's two live counter sets `author.followers`, `author.following`, `author.likes_count` and `author.posts_count` carry: `app` (TikTok's app counters, the default) or `web` (the website's `statsV2`, returned with `counts=web`). The two sets can differ by a few percent in either direction." }, "keywords": { "type": [ "string", "null" ], "description": "String at author.ext.keywords" }, "total_views": { "type": [ "number", "null" ], "description": "Numeric at author.ext.total_views" }, "joined_at_timestamp": { "type": [ "string", "null" ], "description": "String at author.ext.joined_at_timestamp" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at author.ext.topicCategories", "items": { "type": "string", "description": "String at author.ext.topicCategories" } }, "bannerExternalUrl": { "type": [ "string", "null" ], "description": "String at author.ext.bannerExternalUrl" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.madeForKids" }, "hiddenSubscriberCount": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.hiddenSubscriberCount" }, "related_playlists": { "type": [ "object", "null" ], "description": "Object at author.ext.related_playlists" }, "topic_ids": { "type": [ "array", "null" ], "description": "Array at author.ext.topic_ids", "items": { "type": "string", "description": "String at author.ext.topic_ids" } }, "unsubscribed_trailer": { "type": [ "string", "null" ], "description": "String at author.ext.unsubscribed_trailer" }, "localizations": { "type": [ "object", "null" ], "description": "Object at author.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: author.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at author.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at author.ext.localizations.*.description" } } } }, "monthly_listeners": { "type": [ "number", "null" ], "description": "Numeric at author.ext.monthly_listeners" }, "total_ratings": { "type": [ "number", "null" ], "description": "Spotify podcasts only: how many listeners have rated the show. Cumulative over the show's whole run, so it reflects longevity as well as size, and it is NOT an audience count (Spotify publishes no play, download, subscriber or follower count for a podcast)" }, "average_rating": { "type": [ "number", "null" ], "description": "Spotify podcasts only: mean listener rating from 0 to 5. Fractional (e.g. 4.66) despite the integer type this schema emits for every numeric leaf" }, "creator_username": { "type": [ "string", "null" ], "description": "String at author.ext.creator_username" }, "join_policy": { "type": [ "string", "null" ], "description": "String at author.ext.join_policy" }, "is_nsfw": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_nsfw" }, "rules": { "type": [ "array", "null" ], "description": "Array at author.ext.rules", "items": { "type": "object", "description": "Object at author.ext.rules" } }, "weekly_active_users": { "type": [ "number", "null" ], "description": "Numeric at author.ext.weekly_active_users" }, "weekly_contributions": { "type": [ "number", "null" ], "description": "Numeric at author.ext.weekly_contributions" }, "rules_text": { "type": [ "string", "null" ], "description": "String at author.ext.rules_text" }, "language": { "type": [ "string", "null" ], "description": "String at author.ext.language" }, "post_karma": { "type": [ "number", "null" ], "description": "Numeric at author.ext.post_karma" }, "comment_karma": { "type": [ "number", "null" ], "description": "Numeric at author.ext.comment_karma" }, "awardee_karma": { "type": [ "number", "null" ], "description": "Numeric at author.ext.awardee_karma" }, "trophy_count": { "type": [ "number", "null" ], "description": "Numeric at author.ext.trophy_count" }, "banner_url": { "type": [ "string", "null" ], "description": "String at author.ext.banner_url" }, "profile_title": { "type": [ "string", "null" ], "description": "String at author.ext.profile_title" }, "social_links": { "type": [ "array", "null" ], "description": "Array at author.ext.social_links", "items": { "description": "Leaf at author.ext.social_links" } }, "bio_link": { "type": [ "string", "null" ], "description": "String at author.ext.bio_link" }, "embed_html": { "type": [ "string", "null" ], "description": "String at author.ext.embed_html" }, "embed_url": { "type": [ "string", "null" ], "description": "String at author.ext.embed_url" }, "group": { "type": [ "object", "null" ], "description": "Object at author.ext.group" }, "search_hit": { "type": [ "object", "null" ], "description": "Nested object: author.ext.search_hit", "properties": { "match": { "type": [ "string", "null" ], "enum": [ "group_page", "post_in_group", "channel_page", "post_in_channel", null ], "description": "Leaf at author.ext.search_hit.match" }, "title": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.title" }, "snippet": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.snippet" }, "evidence_url": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.evidence_url" }, "matched_urls": { "type": [ "array", "null" ], "description": "Array at author.ext.search_hit.matched_urls", "items": { "type": "string", "description": "String at author.ext.search_hit.matched_urls" } } } }, "blog_name": { "type": [ "string", "null" ], "description": "String at author.ext.blog_name" }, "blog_no": { "type": [ "string", "null" ], "description": "String at author.ext.blog_no" }, "visitors_today": { "type": [ "number", "null" ], "description": "Numeric at author.ext.visitors_today" }, "visitors_total": { "type": [ "number", "null" ], "description": "Numeric at author.ext.visitors_total" }, "topic": { "type": [ "string", "null" ], "description": "String at author.ext.topic" }, "power_blog": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.power_blog" }, "official_blog": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.official_blog" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "number", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "number", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "number", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "number", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "enum": [ "target", "other_named_thing", "generic_word", "not_present" ], "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "number", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "number", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "string", "boolean", "null" ], "description": "Union: number | string | boolean" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } } } }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "author" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached" ] }, "example": { "success": true, "platform": "snapchat", "endpoint": "/v1/snapchat/profile", "data": { "author": { "id": "e9bcdb52-a5cc-4dea-88ac-8baa91a78345", "username": "kyliejenner", "display_name": "King Kylie 👑", "avatar_url": "https://cf-st.sc-cdn.net/aps/bolt/aHR0cHM6Ly9jZi1zdC5zYy1jZG4ubmV0L2QvaEJwN3Z0ZFl5NFVOeFpnWk04dXBYP2JvPUVna3lBUVJJQWxBWllBRSUzRCZ1Yz0yNQ._RS0,90_FMjpeg", "bio": null, "verified": true, "followers": 30657600, "following": null, "posts_count": null, "likes_count": null, "url": "kyliecosmetics.com", "private": false, "joined_at": "2019-05-22" }, "computed": { "engagement_rate": null, "language": null, "content_category": null, "estimated_reach": null } }, "credits_used": 1, "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" } } } } } } }, "/snapchat/spotlight/comments": { "get": { "summary": "List comments on a Snapchat Spotlight", "description": "Returns comments on a Snapchat Spotlight snap. Each comment includes text, display name, reaction count, nested reply count, and timestamp. Page with cursor.", "tags": [ "snapchat" ], "operationId": "get_snapchat_spotlight_comments", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full URL of the Snapchat Spotlight snap.", "schema": { "type": "string" }, "example": "https://www.snapchat.com/@lilah4823/spotlight/W7_EDlXWTBiXAEEniNoMPwAAYY2pvZnd0ZXVmAZ8fgG8pAZ8ff-_IAAAAAQ" }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from the previous response to fetch the next page.", "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 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": "snapchat" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/snapchat/spotlight/comments" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical comment wrappers ({ comment, computed })", "items": { "type": "object", "description": "Canonical comment wrapper", "properties": { "comment": { "type": "object", "description": "Canonical Comment object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific comment ID (always a string)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the comment on the source platform" }, "parent_id": { "type": [ "string", "null" ], "description": "Parent comment ID for nested replies, or null for top-level comments" }, "post_id": { "type": [ "string", "null" ], "description": "ID of the post this comment belongs to" }, "text": { "type": [ "string", "null" ], "description": "Comment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream: customers never see them." }, "author": { "type": "object", "description": "Subset of Author fields for the comment author", "properties": { "username": { "type": [ "string", "null" ], "description": "Comment author username (null when tombstoned)" }, "display_name": { "type": [ "string", "null" ], "description": "Comment author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to comment author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the comment author is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts on the comment", "properties": { "likes": { "type": [ "number", "null" ], "description": "Like / upvote count" }, "replies": { "type": [ "number", "null" ], "description": "Reply / child-comment count. `0` when the upstream structurally reports the count and the comment has no replies; `null` only when the upstream does not surface a reply count at all." } } }, "flags": { "type": "object", "description": "Boolean flags on the comment", "properties": { "pinned": { "type": [ "boolean", "null" ], "description": "Pinned flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the comment is tombstoned (always present, even when false)" }, "liked_by_creator": { "type": [ "boolean", "null" ], "description": "`/v1/instagram/post/comments` only: true when the post's creator liked (hearted) the comment, false when not, null when the source that served the call could not tell. Absent on every other endpoint." } } }, "published_at": { "type": [ "string", "number", "null" ], "description": "Comment creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `comment.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough tokens for reply expansion (present only on platforms that surface them)", "properties": { "replies_token": { "type": [ "string", "null" ], "description": "YouTube reply continuation token: pass to `/v1/youtube/video/comment/replies?continuationToken=`" }, "replies_cursor": { "type": [ "string", "null" ], "description": "Reddit reply-branch continuation cursor. Present when this comment's reply tree is truncated upstream: pass it back as `?cursor=` on `/v1/reddit/post/comments` to load the rest of the branch." }, "depth": { "type": [ "number", "null" ], "description": "Reddit comment nesting depth as the source reports it: 0 on a top-level comment, 1 on a direct reply, and so on. Present when the thread arrived flat and was re-nested into `replies[]`, so you can verify that nesting independently." }, "published_at_epoch": { "type": [ "number", "null" ], "description": "Raw Unix epoch for `published_at` (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string)." }, "feedback_id": { "type": [ "string", "null" ], "description": "Facebook comment feedback id: feeds `/v1/facebook/post/comment/replies`" }, "expansion_token": { "type": [ "string", "null" ], "description": "Facebook comment expansion/paginator token: feeds `/v1/facebook/post/comment/replies`" }, "author_id": { "type": [ "string", "null" ], "description": "The commenter's platform-native numeric user id, where the upstream exposes one." }, "ip_location": { "type": [ "string", "null" ], "description": "String at comment.ext.ip_location" }, "urn": { "type": [ "string", "null" ], "description": "String at comment.ext.urn" }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at comment.ext.reaction_counts", "items": { "description": "Leaf at comment.ext.reaction_counts" } }, "is_edited": { "type": [ "boolean", "null" ], "description": "Boolean at comment.ext.is_edited" }, "previous_replies_token": { "type": [ "string", "null" ], "description": "String at comment.ext.previous_replies_token" }, "author_headline": { "type": [ "string", "null" ], "description": "String at comment.ext.author_headline" }, "updated_at": { "type": [ "string", "null" ], "description": "String at comment.ext.updated_at" }, "author_channel_id": { "type": [ "string", "null" ], "description": "String at comment.ext.author_channel_id" }, "author_url": { "type": [ "string", "null" ], "description": "String at comment.ext.author_url" }, "viewer_rating": { "type": [ "string", "null" ], "description": "String at comment.ext.viewer_rating" }, "text_original": { "type": [ "string", "null" ], "description": "String at comment.ext.text_original" }, "preview_replies": { "type": [ "array", "null" ], "description": "Array at comment.ext.preview_replies", "items": { "description": "Leaf at comment.ext.preview_replies" } }, "lookup": { "type": [ "object", "null" ], "description": "Object at comment.ext.lookup" }, "post_title": { "type": [ "string", "null" ], "description": "String at comment.ext.post_title" }, "post_url": { "type": [ "string", "null" ], "description": "String at comment.ext.post_url" }, "subreddit": { "type": [ "string", "null" ], "description": "String at comment.ext.subreddit" }, "subreddit_subscribers": { "type": [ "number", "null" ], "description": "Numeric at comment.ext.subreddit_subscribers" }, "post_score": { "type": [ "number", "null" ], "description": "Numeric at comment.ext.post_score" }, "post_comment_count": { "type": [ "number", "null" ], "description": "Numeric at comment.ext.post_comment_count" }, "post_author": { "type": [ "string", "null" ], "description": "String at comment.ext.post_author" }, "post_published_at": { "type": [ "string", "null" ], "description": "String at comment.ext.post_published_at" }, "post_flair": { "type": [ "string", "null" ], "description": "String at comment.ext.post_flair" }, "is_submitter": { "type": [ "boolean", "null" ], "description": "Boolean at comment.ext.is_submitter" }, "edited_at": { "type": [ "string", "null" ], "description": "String at comment.ext.edited_at" }, "controversiality": { "type": [ "number", "null" ], "description": "Numeric at comment.ext.controversiality" }, "content_language": { "type": [ "string", "null" ], "description": "ISO 639-1 language tag for this comment, when the source reports one. X writes `zxx` / `und` for no linguistic content; those collapse to null." }, "author_followers": { "type": [ "number", "null" ], "description": "The commenter's follower count as embedded in this row. Snapshot as of whenever the replies source saw the account, not a live figure. On X this is present on every `tweet/replies` row." }, "author_following": { "type": [ "number", "null" ], "description": "The commenter's following count as embedded in this row. Same snapshot caveat as `author_followers`." }, "author_posts_count": { "type": [ "number", "null" ], "description": "The commenter's post count as embedded in this row. Same snapshot caveat as `author_followers`." }, "author_location": { "type": [ "string", "null" ], "description": "String at comment.ext.author_location" }, "quote_count": { "type": [ "number", "null" ], "description": "How many quote-posts this comment has, when the source reports it. On X a reply is a tweet, so this is the same figure `post.ext.quote_count` carries on tweet lanes." }, "views": { "type": [ "number", "null" ], "description": "View count for this comment, when the source reports it. On X a reply is a tweet and the count is public on posts from ~2022 onward." }, "saves": { "type": [ "number", "null" ], "description": "Bookmark / save count for this comment, when the source reports it. On X this is `legacy.bookmark_count`." } } }, "replies": { "type": [ "array", "null" ], "description": "Nested reply tree: array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`.", "items": { "type": "object", "description": "Nested reply tree: array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`." } } } }, "computed": { "type": "object", "description": "Server-computed fields for this comment", "properties": { "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the comment text, or the platform's own label when it publishes one. Null when undetectable." }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "null" ], "description": "Numeric at computed.labels.*.*" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "comment_recency": { "type": "object", "description": "Present on every comment list. How alive the thread is, from the comments on this page and the post's age. Rows are not dropped or reordered.", "properties": { "policy_version": { "type": "string", "description": "The version of the cuts used.", "example": "d09-1" }, "n": { "type": "integer", "description": "Comments considered, replies included.", "example": 50 }, "counted": { "type": "integer", "description": "Comments with a usable date.", "example": 50 }, "abstained": { "type": "integer", "description": "Comments with no usable date.", "example": 0 }, "share_last_24h": { "type": [ "number", "null" ], "description": "Share of dated comments written in the last 24 hours, from 0 to 1. A floor when `recent_share_is_floor` is true.", "example": 0.22 }, "share_later_half": { "type": [ "number", "null" ], "description": "Share of dated comments written in the later half of the post's life so far. Null when the post's date is unknown.", "example": 0.6 }, "too_few": { "type": "boolean", "description": "True when fewer than 8 comments are dated, so `stage` is `unknown`.", "example": false }, "stage": { "type": "string", "enum": [ "alive", "slowing", "spent", "too_young", "unknown" ], "description": "`alive`: comments are still arriving. `slowing`: fewer are arriving. `spent`: the thread has gone quiet. `too_young`: the post is under a day old. `unknown`: too few dated comments to say.", "example": "alive" }, "order": { "type": "string", "enum": [ "recent", "top", "default" ], "description": "The order this page was read in.", "example": "recent" }, "recent_share_is_floor": { "type": "boolean", "description": "True when the page was not read newest first, so newer comments may sit on a page you did not read and `share_last_24h` is at least this value.", "example": false }, "receipts": { "type": "array", "description": "Up to three of the newest comments from the last 24 hours, with their text copied unchanged.", "items": { "type": "object", "description": "One verbatim receipt: a row that counted toward the share.", "properties": { "id": { "type": "string", "description": "The row's id." }, "text": { "type": "string", "description": "The row's text, copied unchanged." } } } } } }, "walk": { "type": "object", "description": "Present when the request sent a row-walk param (`max_pages` above 1, `max_items`, `max_credits`, a row filter, `sort_rows` or `seen`). What the walk did across the pages it fetched. Each page is billed as one call, and its charge is recorded under its own request id.", "properties": { "pages": { "type": "integer", "description": "Pages fetched.", "example": 3 }, "stopped": { "type": "string", "enum": [ "end", "max_pages", "max_items", "max_credits", "time_budget", "page_error" ], "description": "Why the walk stopped. `end`: the list ran out. `max_pages`, `max_items` or `max_credits`: the limit you set was reached. `time_budget`: the request's time budget ran low. `page_error`: a later page failed. Unless it is `end`, `pagination.next_cursor` continues from where the walk stopped.", "example": "max_pages" }, "rows_fetched": { "type": "integer", "description": "Rows read across every page, before any filter.", "example": 60 }, "rows_returned": { "type": "integer", "description": "Rows in `data.items`.", "example": 41 }, "discarded": { "type": "object", "description": "Present when you sent a row filter. Rows the filters removed, counted once each under the first filter they failed. A row a filter cannot verify (no view count, no date, no country) is discarded.", "properties": { "views_below_min": { "type": "integer", "description": "Rows with fewer views than `min_views`." }, "views_unknown": { "type": "integer", "description": "Rows with no view count, when `min_views` was sent." }, "older_than_max_age": { "type": "integer", "description": "Rows published before the `max_age_days` window." }, "date_unknown": { "type": "integer", "description": "Rows with no publish date, when `max_age_days` was sent." }, "country_not_included": { "type": "integer", "description": "Rows registered to a country that is not in `country`." }, "country_unknown": { "type": "integer", "description": "Rows with no country, when `country` was sent." }, "country_excluded": { "type": "integer", "description": "Rows registered to a country listed in `exclude_country`." } } }, "repeats": { "type": "integer", "description": "Present when you sent `seen`: rows removed because your account already received them under that id." }, "duplicates": { "type": "integer", "description": "Present when above zero: rows a later page repeated from an earlier page of the same walk, kept once." }, "credits": { "type": "object", "description": "What the pages cost.", "properties": { "pages": { "type": "integer", "description": "Credits charged for the pages walked, before refunds." }, "refunded": { "type": "integer", "description": "Credits refunded across the pages." } } }, "request_ids": { "type": "array", "description": "The request id of each page walked. Each is its own entry in `GET /v1/credits/transactions`.", "items": { "type": "string", "description": "A row id." } } } }, "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": "snapchat", "endpoint": "/v1/snapchat/spotlight/comments", "data": { "items": [ { "comment": { "id": "158093169738028328999281183403928747727", "url": null, "parent_id": null, "post_id": "W7_EDlXWTBiXAEEniNoMPwAAYY2pvZnd0ZXVmAZ8fgG8pAZ8ff-_IAAAAAQ", "text": "Sample comment text (redacted).", "author": { "username": null, "display_name": "user_606f3a", "avatar_url": null, "verified": null }, "engagement": { "likes": 704, "replies": 62 }, "flags": { "pinned": null, "deleted": false }, "published_at": "2026-07-01T21:19:35.639Z", "ext": { "published_at_epoch": 1782940775639 } }, "computed": { "language": "en" } }, { "comment": { "id": "313223440109170257811951610601913719819", "url": null, "parent_id": null, "post_id": "W7_EDlXWTBiXAEEniNoMPwAAYY2pvZnd0ZXVmAZ8fgG8pAZ8ff-_IAAAAAQ", "text": "Sample comment text (redacted).", "author": { "username": null, "display_name": "user_db74c9", "avatar_url": null, "verified": null }, "engagement": { "likes": 620, "replies": 68 }, "flags": { "pinned": null, "deleted": false }, "published_at": "2026-07-02T21:39:57.434Z", "ext": { "published_at_epoch": 1783028397434 } }, "computed": { "language": "en" } } ], "next_cursor": "CAESVfq8iY0Il/Lx3QGE/NCoBJjto6UK7dCzmw7u4d7CD5GT9qABp+/vsA+BteamBeLg0KMOysTs7AzM2/LBB4PX8bgCtdvIwAWF3LzND5+dnNIJ6pikpwwagwISgAJDcjBCQ2cwS0FuUnpFZ2NJbVBIby1QVXpFcWNCYWhkemZtUmxiSFJoTFdadmNtTmxMVzVoYlRVdGNISnZaSEtMQVFzU0VGTndiM1JzYVdkb2RGSmxjR3hwWlhNaU8xYzNYMFZFYkZoWFZFSnBXRUZGUlc1cFRtOU5VSGRCUVZsWk1uQjJXbTVrTUZwWVZtMUJXamhtWjBjNGNFRmFPR1ptTFY5SlFVRkJRVUZSREFzU0VGTndiM1JzYVdkb2RGSmxjR3hwWlhNaUpEUTFNamswTkRVeExXUTVNall0TkRsaE9TMDVOVGN4TFRWaU1ESmhObUU1WVRKbU5Bd1lBQ0FC", "total": null, "comment_recency": { "policy_version": "d09-1", "n": 25, "counted": 25, "abstained": 0, "share_last_24h": 0, "share_later_half": null, "too_few": false, "stage": "unknown", "order": "default", "recent_share_is_floor": true, "receipts": [] }, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiQ0FFU1ZmcThpWTBJbC9MeDNRR0UvTkNvQkpqdG82VUs3ZEN6bXc3dTRkN0NENUdUOXFBQnArL3ZzQStCdGVhbUJlTGcwS01PeXNUczdBek0yL0xCQjRQWDhiZ0N0ZHZJd0FXRjNMek5ENStkbk5JSjZwaWtwd3dhZ3dJU2dBSkRjakJDUTJjd1MwRnVVbnBGWjJOSmJWQklieTFRVlhwRmNXTkNZV2hrZW1adFVteGlTRkpvVEZkYWRtTnRUbXhNVnpWb1lsUlZkR05JU25aYVNFdE1RVkZ6VTBWR1RuZGlNMUp6WVZka2IyUkdTbXhqUjNod1dsaE5hVTh4WXpOWU1GWkZZa1pvV0ZaRlNuQlhSVVpHVWxjMWNGUnRPVTVWU0dSQ1VWWnNXazF1UWpKWGJUVnJUVVp3V1ZadE1VSlhhbWh0V2pCak5HTkZSbUZQUjFwdFRGWTVTbEZWUmtKUlZVWlNSRUZ6VTBWR1RuZGlNMUp6WVZka2IyUkdTbXhqUjNod1dsaE5hVXBFVVRGTmFtc3dUa1JWZUV4WFVUVk5hbGwwVGtSc2FFOVRNRFZPVkdONFRGUldhVTFFU21oT2JVVTFXVlJLYlU1QmQxbEJRMEZDIiwiZSI6InNuYXBjaGF0L3Nwb3RsaWdodC9jb21tZW50cyIsInAiOiJjdXJzb3IifQ", "has_more": true, "page_size": 25 }, "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" } } } } } } } }, "x-full-spec": "https://www.socialcrawl.dev/v1/openapi.json" }